From f8170e3c46192c9cb82bdb6239cf985794293997 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Fri, 30 Oct 2020 17:45:58 +0200 Subject: [PATCH] Move everything into the sys subdirectory --- .gitmodules | 3 - gir | 1 - gir-files/GES-1.0.gir | 16022 --- gir-files/GLib-2.0.gir | 51822 --------- gir-files/GModule-2.0.gir | 266 - gir-files/GObject-2.0.gir | 17463 --- gir-files/Gio-2.0.gir | 89324 ---------------- gir-files/Gst-1.0.gir | 52746 --------- gir-files/GstApp-1.0.gir | 1967 - gir-files/GstAudio-1.0.gir | 10671 -- gir-files/GstBase-1.0.gir | 13869 --- gir-files/GstCheck-1.0.gir | 3038 - gir-files/GstController-1.0.gir | 1075 - gir-files/GstGL-1.0.gir | 11015 -- gir-files/GstMpegts-1.0.gir | 4711 - gir-files/GstNet-1.0.gir | 914 - gir-files/GstPbutils-1.0.gir | 4107 - gir-files/GstPlayer-1.0.gir | 2410 - gir-files/GstRtp-1.0.gir | 5548 - gir-files/GstRtsp-1.0.gir | 4769 - gir-files/GstRtspServer-1.0.gir | 12228 --- gir-files/GstSdp-1.0.gir | 4290 - gir-files/GstTag-1.0.gir | 1765 - gir-files/GstVideo-1.0.gir | 16492 --- gir-files/GstWebRTC-1.0.gir | 1431 - gir-files/fix.sh | 97 - .gitignore => sys/.gitignore | 0 .gitlab-ci.yml => sys/.gitlab-ci.yml | 0 Cargo.toml => sys/Cargo.toml | 0 DEVELOPMENT.md => sys/DEVELOPMENT.md | 0 Gir_Gst.toml => sys/Gir_Gst.toml | 0 Gir_GstApp.toml => sys/Gir_GstApp.toml | 0 Gir_GstAudio.toml => sys/Gir_GstAudio.toml | 0 Gir_GstBase.toml => sys/Gir_GstBase.toml | 0 Gir_GstCheck.toml => sys/Gir_GstCheck.toml | 0 .../Gir_GstController.toml | 0 .../Gir_GstEditingServices.toml | 0 Gir_GstGL.toml => sys/Gir_GstGL.toml | 0 Gir_GstMpegts.toml => sys/Gir_GstMpegts.toml | 0 Gir_GstNet.toml => sys/Gir_GstNet.toml | 0 .../Gir_GstPbutils.toml | 0 Gir_GstPlayer.toml => sys/Gir_GstPlayer.toml | 0 Gir_GstRtp.toml => sys/Gir_GstRtp.toml | 0 Gir_GstRtsp.toml => sys/Gir_GstRtsp.toml | 0 .../Gir_GstRtspServer.toml | 0 Gir_GstSdp.toml => sys/Gir_GstSdp.toml | 0 Gir_GstTag.toml => sys/Gir_GstTag.toml | 0 Gir_GstVideo.toml => sys/Gir_GstVideo.toml | 0 Gir_GstWebRTC.toml => sys/Gir_GstWebRTC.toml | 0 LICENSE => sys/LICENSE | 0 README.md => sys/README.md | 0 {ci => sys/ci}/env.sh | 0 deny.toml => sys/deny.toml | 0 generator.py => sys/generator.py | 0 .../gstreamer-app-sys}/CHANGELOG.md | 0 .../gstreamer-app-sys}/Cargo.toml | 0 .../gstreamer-app-sys}/LICENSE | 0 .../gstreamer-app-sys}/README.md | 0 .../gstreamer-app-sys}/build.rs | 0 .../gstreamer-app-sys}/src/lib.rs | 0 .../gstreamer-app-sys}/tests/abi.rs | 0 .../gstreamer-app-sys}/tests/constant.c | 0 .../gstreamer-app-sys}/tests/layout.c | 0 .../gstreamer-app-sys}/tests/manual.h | 0 .../gstreamer-audio-sys}/CHANGELOG.md | 0 .../gstreamer-audio-sys}/Cargo.toml | 0 .../gstreamer-audio-sys}/LICENSE | 0 .../gstreamer-audio-sys}/README.md | 0 .../gstreamer-audio-sys}/build.rs | 0 .../gstreamer-audio-sys}/src/lib.rs | 0 .../gstreamer-audio-sys}/tests/abi.rs | 0 .../gstreamer-audio-sys}/tests/constant.c | 0 .../gstreamer-audio-sys}/tests/layout.c | 0 .../gstreamer-audio-sys}/tests/manual.h | 0 .../gstreamer-base-sys}/CHANGELOG.md | 0 .../gstreamer-base-sys}/Cargo.toml | 0 .../gstreamer-base-sys}/LICENSE | 0 .../gstreamer-base-sys}/README.md | 0 .../gstreamer-base-sys}/build.rs | 0 .../gstreamer-base-sys}/src/lib.rs | 0 .../gstreamer-base-sys}/tests/abi.rs | 0 .../gstreamer-base-sys}/tests/constant.c | 0 .../gstreamer-base-sys}/tests/layout.c | 0 .../gstreamer-base-sys}/tests/manual.h | 0 .../gstreamer-check-sys}/CHANGELOG.md | 0 .../gstreamer-check-sys}/Cargo.toml | 0 .../gstreamer-check-sys}/LICENSE | 0 .../gstreamer-check-sys}/README.md | 0 .../gstreamer-check-sys}/build.rs | 0 .../gstreamer-check-sys}/src/lib.rs | 0 .../gstreamer-check-sys}/tests/abi.rs | 0 .../gstreamer-check-sys}/tests/constant.c | 0 .../gstreamer-check-sys}/tests/layout.c | 0 .../gstreamer-check-sys}/tests/manual.h | 0 .../gstreamer-controller-sys}/CHANGELOG.md | 0 .../gstreamer-controller-sys}/Cargo.toml | 0 .../gstreamer-controller-sys}/README.md | 0 .../gstreamer-controller-sys}/build.rs | 0 .../gstreamer-controller-sys}/src/lib.rs | 0 .../gstreamer-controller-sys}/tests/abi.rs | 0 .../tests/constant.c | 0 .../gstreamer-controller-sys}/tests/layout.c | 0 .../gstreamer-controller-sys}/tests/manual.h | 0 .../CHANGELOG.md | 0 .../Cargo.toml | 0 .../gstreamer-editing-services-sys}/README.md | 0 .../gstreamer-editing-services-sys}/build.rs | 0 .../src/lib.rs | 0 .../tests/abi.rs | 0 .../tests/constant.c | 0 .../tests/layout.c | 0 .../tests/manual.h | 0 .../gstreamer-gl-sys}/CHANGELOG.md | 0 .../gstreamer-gl-sys}/Cargo.toml | 0 .../gstreamer-gl-sys}/README.md | 0 .../gstreamer-gl-sys}/build.rs | 0 .../gstreamer-gl-sys}/src/lib.rs | 0 .../gstreamer-gl-sys}/src/manual.rs | 0 .../gstreamer-gl-sys}/tests/abi.rs | 0 .../gstreamer-gl-sys}/tests/constant.c | 0 .../gstreamer-gl-sys}/tests/layout.c | 0 .../gstreamer-gl-sys}/tests/manual.h | 0 .../gstreamer-mpegts-sys}/CHANGELOG.md | 0 .../gstreamer-mpegts-sys}/Cargo.toml | 0 .../gstreamer-mpegts-sys}/LICENSE | 0 .../gstreamer-mpegts-sys}/README.md | 0 .../gstreamer-mpegts-sys}/build.rs | 0 .../gstreamer-mpegts-sys}/src/lib.rs | 0 .../gstreamer-mpegts-sys}/tests/abi.rs | 0 .../gstreamer-mpegts-sys}/tests/constant.c | 0 .../gstreamer-mpegts-sys}/tests/layout.c | 0 .../gstreamer-mpegts-sys}/tests/manual.h | 0 .../gstreamer-net-sys}/CHANGELOG.md | 0 .../gstreamer-net-sys}/Cargo.toml | 0 .../gstreamer-net-sys}/LICENSE | 0 .../gstreamer-net-sys}/README.md | 0 .../gstreamer-net-sys}/build.rs | 0 .../gstreamer-net-sys}/src/lib.rs | 0 .../gstreamer-net-sys}/tests/abi.rs | 0 .../gstreamer-net-sys}/tests/constant.c | 0 .../gstreamer-net-sys}/tests/layout.c | 0 .../gstreamer-net-sys}/tests/manual.h | 0 .../gstreamer-pbutils-sys}/CHANGELOG.md | 0 .../gstreamer-pbutils-sys}/Cargo.toml | 0 .../gstreamer-pbutils-sys}/LICENSE | 0 .../gstreamer-pbutils-sys}/README.md | 0 .../gstreamer-pbutils-sys}/build.rs | 0 .../gstreamer-pbutils-sys}/src/lib.rs | 0 .../gstreamer-pbutils-sys}/tests/abi.rs | 0 .../gstreamer-pbutils-sys}/tests/constant.c | 0 .../gstreamer-pbutils-sys}/tests/layout.c | 0 .../gstreamer-pbutils-sys}/tests/manual.h | 0 .../gstreamer-player-sys}/CHANGELOG.md | 0 .../gstreamer-player-sys}/Cargo.toml | 0 .../gstreamer-player-sys}/LICENSE | 0 .../gstreamer-player-sys}/README.md | 0 .../gstreamer-player-sys}/build.rs | 0 .../gstreamer-player-sys}/src/lib.rs | 0 .../gstreamer-player-sys}/tests/abi.rs | 0 .../gstreamer-player-sys}/tests/constant.c | 0 .../gstreamer-player-sys}/tests/layout.c | 0 .../gstreamer-player-sys}/tests/manual.h | 0 .../gstreamer-rtp-sys}/CHANGELOG.md | 0 .../gstreamer-rtp-sys}/Cargo.toml | 0 .../gstreamer-rtp-sys}/README.md | 0 .../gstreamer-rtp-sys}/build.rs | 0 .../gstreamer-rtp-sys}/src/lib.rs | 0 .../gstreamer-rtp-sys}/tests/abi.rs | 0 .../gstreamer-rtp-sys}/tests/constant.c | 0 .../gstreamer-rtp-sys}/tests/layout.c | 0 .../gstreamer-rtp-sys}/tests/manual.h | 0 .../gstreamer-rtsp-server-sys}/CHANGELOG.md | 0 .../gstreamer-rtsp-server-sys}/Cargo.toml | 0 .../gstreamer-rtsp-server-sys}/LICENSE | 0 .../gstreamer-rtsp-server-sys}/README.md | 0 .../gstreamer-rtsp-server-sys}/build.rs | 0 .../gstreamer-rtsp-server-sys}/src/lib.rs | 0 .../gstreamer-rtsp-server-sys}/tests/abi.rs | 0 .../tests/constant.c | 0 .../gstreamer-rtsp-server-sys}/tests/layout.c | 0 .../gstreamer-rtsp-server-sys}/tests/manual.h | 0 .../gstreamer-rtsp-sys}/CHANGELOG.md | 0 .../gstreamer-rtsp-sys}/Cargo.toml | 0 .../gstreamer-rtsp-sys}/LICENSE | 0 .../gstreamer-rtsp-sys}/README.md | 0 .../gstreamer-rtsp-sys}/build.rs | 0 .../gstreamer-rtsp-sys}/src/lib.rs | 0 .../gstreamer-rtsp-sys}/tests/abi.rs | 0 .../gstreamer-rtsp-sys}/tests/constant.c | 0 .../gstreamer-rtsp-sys}/tests/layout.c | 0 .../gstreamer-rtsp-sys}/tests/manual.h | 0 .../gstreamer-sdp-sys}/CHANGELOG.md | 0 .../gstreamer-sdp-sys}/Cargo.toml | 0 .../gstreamer-sdp-sys}/LICENSE | 0 .../gstreamer-sdp-sys}/README.md | 0 .../gstreamer-sdp-sys}/build.rs | 0 .../gstreamer-sdp-sys}/src/lib.rs | 0 .../gstreamer-sdp-sys}/tests/abi.rs | 0 .../gstreamer-sdp-sys}/tests/constant.c | 0 .../gstreamer-sdp-sys}/tests/layout.c | 0 .../gstreamer-sdp-sys}/tests/manual.h | 0 .../gstreamer-sys}/CHANGELOG.md | 0 .../gstreamer-sys}/Cargo.lock | 0 .../gstreamer-sys}/Cargo.toml | 0 {gstreamer-sys => sys/gstreamer-sys}/LICENSE | 0 .../gstreamer-sys}/README.md | 0 {gstreamer-sys => sys/gstreamer-sys}/build.rs | 0 .../gstreamer-sys}/src/lib.rs | 0 .../gstreamer-sys}/tests/abi.rs | 0 .../gstreamer-sys}/tests/constant.c | 0 .../gstreamer-sys}/tests/layout.c | 0 .../gstreamer-sys}/tests/manual.h | 0 .../gstreamer-tag-sys}/CHANGELOG.md | 0 .../gstreamer-tag-sys}/Cargo.toml | 0 .../gstreamer-tag-sys}/LICENSE | 0 .../gstreamer-tag-sys}/README.md | 0 .../gstreamer-tag-sys}/build.rs | 0 .../gstreamer-tag-sys}/src/lib.rs | 0 .../gstreamer-tag-sys}/tests/abi.rs | 0 .../gstreamer-tag-sys}/tests/constant.c | 0 .../gstreamer-tag-sys}/tests/layout.c | 0 .../gstreamer-tag-sys}/tests/manual.h | 0 .../gstreamer-video-sys}/CHANGELOG.md | 0 .../gstreamer-video-sys}/Cargo.toml | 0 .../gstreamer-video-sys}/LICENSE | 0 .../gstreamer-video-sys}/README.md | 0 .../gstreamer-video-sys}/build.rs | 0 .../gstreamer-video-sys}/src/lib.rs | 0 .../gstreamer-video-sys}/tests/abi.rs | 0 .../gstreamer-video-sys}/tests/constant.c | 0 .../gstreamer-video-sys}/tests/layout.c | 0 .../gstreamer-video-sys}/tests/manual.h | 0 .../gstreamer-webrtc-sys}/CHANGELOG.md | 0 .../gstreamer-webrtc-sys}/Cargo.toml | 0 .../gstreamer-webrtc-sys}/README.md | 0 .../gstreamer-webrtc-sys}/build.rs | 0 .../gstreamer-webrtc-sys}/src/lib.rs | 0 .../gstreamer-webrtc-sys}/tests/abi.rs | 0 .../gstreamer-webrtc-sys}/tests/constant.c | 0 .../gstreamer-webrtc-sys}/tests/layout.c | 0 .../gstreamer-webrtc-sys}/tests/manual.h | 0 241 files changed, 328044 deletions(-) delete mode 100644 .gitmodules delete mode 160000 gir delete mode 100644 gir-files/GES-1.0.gir delete mode 100644 gir-files/GLib-2.0.gir delete mode 100644 gir-files/GModule-2.0.gir delete mode 100644 gir-files/GObject-2.0.gir delete mode 100644 gir-files/Gio-2.0.gir delete mode 100644 gir-files/Gst-1.0.gir delete mode 100644 gir-files/GstApp-1.0.gir delete mode 100644 gir-files/GstAudio-1.0.gir delete mode 100644 gir-files/GstBase-1.0.gir delete mode 100644 gir-files/GstCheck-1.0.gir delete mode 100644 gir-files/GstController-1.0.gir delete mode 100644 gir-files/GstGL-1.0.gir delete mode 100644 gir-files/GstMpegts-1.0.gir delete mode 100644 gir-files/GstNet-1.0.gir delete mode 100644 gir-files/GstPbutils-1.0.gir delete mode 100644 gir-files/GstPlayer-1.0.gir delete mode 100644 gir-files/GstRtp-1.0.gir delete mode 100644 gir-files/GstRtsp-1.0.gir delete mode 100644 gir-files/GstRtspServer-1.0.gir delete mode 100644 gir-files/GstSdp-1.0.gir delete mode 100644 gir-files/GstTag-1.0.gir delete mode 100644 gir-files/GstVideo-1.0.gir delete mode 100644 gir-files/GstWebRTC-1.0.gir delete mode 100755 gir-files/fix.sh rename .gitignore => sys/.gitignore (100%) rename .gitlab-ci.yml => sys/.gitlab-ci.yml (100%) rename Cargo.toml => sys/Cargo.toml (100%) rename DEVELOPMENT.md => sys/DEVELOPMENT.md (100%) rename Gir_Gst.toml => sys/Gir_Gst.toml (100%) rename Gir_GstApp.toml => sys/Gir_GstApp.toml (100%) rename Gir_GstAudio.toml => sys/Gir_GstAudio.toml (100%) rename Gir_GstBase.toml => sys/Gir_GstBase.toml (100%) rename Gir_GstCheck.toml => sys/Gir_GstCheck.toml (100%) rename Gir_GstController.toml => sys/Gir_GstController.toml (100%) rename Gir_GstEditingServices.toml => sys/Gir_GstEditingServices.toml (100%) rename Gir_GstGL.toml => sys/Gir_GstGL.toml (100%) rename Gir_GstMpegts.toml => sys/Gir_GstMpegts.toml (100%) rename Gir_GstNet.toml => sys/Gir_GstNet.toml (100%) rename Gir_GstPbutils.toml => sys/Gir_GstPbutils.toml (100%) rename Gir_GstPlayer.toml => sys/Gir_GstPlayer.toml (100%) rename Gir_GstRtp.toml => sys/Gir_GstRtp.toml (100%) rename Gir_GstRtsp.toml => sys/Gir_GstRtsp.toml (100%) rename Gir_GstRtspServer.toml => sys/Gir_GstRtspServer.toml (100%) rename Gir_GstSdp.toml => sys/Gir_GstSdp.toml (100%) rename Gir_GstTag.toml => sys/Gir_GstTag.toml (100%) rename Gir_GstVideo.toml => sys/Gir_GstVideo.toml (100%) rename Gir_GstWebRTC.toml => sys/Gir_GstWebRTC.toml (100%) rename LICENSE => sys/LICENSE (100%) rename README.md => sys/README.md (100%) rename {ci => sys/ci}/env.sh (100%) rename deny.toml => sys/deny.toml (100%) rename generator.py => sys/generator.py (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/CHANGELOG.md (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/Cargo.toml (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/LICENSE (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/README.md (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/build.rs (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/src/lib.rs (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/tests/abi.rs (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/tests/constant.c (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/tests/layout.c (100%) rename {gstreamer-app-sys => sys/gstreamer-app-sys}/tests/manual.h (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/CHANGELOG.md (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/Cargo.toml (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/LICENSE (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/README.md (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/build.rs (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/src/lib.rs (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/tests/abi.rs (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/tests/constant.c (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/tests/layout.c (100%) rename {gstreamer-audio-sys => sys/gstreamer-audio-sys}/tests/manual.h (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/CHANGELOG.md (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/Cargo.toml (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/LICENSE (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/README.md (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/build.rs (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/src/lib.rs (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/tests/abi.rs (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/tests/constant.c (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/tests/layout.c (100%) rename {gstreamer-base-sys => sys/gstreamer-base-sys}/tests/manual.h (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/CHANGELOG.md (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/Cargo.toml (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/LICENSE (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/README.md (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/build.rs (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/src/lib.rs (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/tests/abi.rs (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/tests/constant.c (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/tests/layout.c (100%) rename {gstreamer-check-sys => sys/gstreamer-check-sys}/tests/manual.h (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/CHANGELOG.md (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/Cargo.toml (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/README.md (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/build.rs (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/src/lib.rs (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/tests/abi.rs (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/tests/constant.c (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/tests/layout.c (100%) rename {gstreamer-controller-sys => sys/gstreamer-controller-sys}/tests/manual.h (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/CHANGELOG.md (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/Cargo.toml (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/README.md (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/build.rs (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/src/lib.rs (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/tests/abi.rs (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/tests/constant.c (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/tests/layout.c (100%) rename {gstreamer-editing-services-sys => sys/gstreamer-editing-services-sys}/tests/manual.h (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/CHANGELOG.md (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/Cargo.toml (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/README.md (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/build.rs (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/src/lib.rs (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/src/manual.rs (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/tests/abi.rs (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/tests/constant.c (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/tests/layout.c (100%) rename {gstreamer-gl-sys => sys/gstreamer-gl-sys}/tests/manual.h (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/CHANGELOG.md (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/Cargo.toml (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/LICENSE (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/README.md (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/build.rs (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/src/lib.rs (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/tests/abi.rs (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/tests/constant.c (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/tests/layout.c (100%) rename {gstreamer-mpegts-sys => sys/gstreamer-mpegts-sys}/tests/manual.h (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/CHANGELOG.md (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/Cargo.toml (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/LICENSE (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/README.md (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/build.rs (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/src/lib.rs (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/tests/abi.rs (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/tests/constant.c (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/tests/layout.c (100%) rename {gstreamer-net-sys => sys/gstreamer-net-sys}/tests/manual.h (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/CHANGELOG.md (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/Cargo.toml (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/LICENSE (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/README.md (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/build.rs (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/src/lib.rs (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/tests/abi.rs (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/tests/constant.c (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/tests/layout.c (100%) rename {gstreamer-pbutils-sys => sys/gstreamer-pbutils-sys}/tests/manual.h (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/CHANGELOG.md (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/Cargo.toml (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/LICENSE (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/README.md (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/build.rs (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/src/lib.rs (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/tests/abi.rs (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/tests/constant.c (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/tests/layout.c (100%) rename {gstreamer-player-sys => sys/gstreamer-player-sys}/tests/manual.h (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/CHANGELOG.md (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/Cargo.toml (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/README.md (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/build.rs (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/src/lib.rs (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/tests/abi.rs (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/tests/constant.c (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/tests/layout.c (100%) rename {gstreamer-rtp-sys => sys/gstreamer-rtp-sys}/tests/manual.h (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/CHANGELOG.md (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/Cargo.toml (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/LICENSE (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/README.md (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/build.rs (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/src/lib.rs (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/tests/abi.rs (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/tests/constant.c (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/tests/layout.c (100%) rename {gstreamer-rtsp-server-sys => sys/gstreamer-rtsp-server-sys}/tests/manual.h (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/CHANGELOG.md (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/Cargo.toml (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/LICENSE (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/README.md (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/build.rs (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/src/lib.rs (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/tests/abi.rs (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/tests/constant.c (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/tests/layout.c (100%) rename {gstreamer-rtsp-sys => sys/gstreamer-rtsp-sys}/tests/manual.h (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/CHANGELOG.md (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/Cargo.toml (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/LICENSE (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/README.md (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/build.rs (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/src/lib.rs (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/tests/abi.rs (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/tests/constant.c (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/tests/layout.c (100%) rename {gstreamer-sdp-sys => sys/gstreamer-sdp-sys}/tests/manual.h (100%) rename {gstreamer-sys => sys/gstreamer-sys}/CHANGELOG.md (100%) rename {gstreamer-sys => sys/gstreamer-sys}/Cargo.lock (100%) rename {gstreamer-sys => sys/gstreamer-sys}/Cargo.toml (100%) rename {gstreamer-sys => sys/gstreamer-sys}/LICENSE (100%) rename {gstreamer-sys => sys/gstreamer-sys}/README.md (100%) rename {gstreamer-sys => sys/gstreamer-sys}/build.rs (100%) rename {gstreamer-sys => sys/gstreamer-sys}/src/lib.rs (100%) rename {gstreamer-sys => sys/gstreamer-sys}/tests/abi.rs (100%) rename {gstreamer-sys => sys/gstreamer-sys}/tests/constant.c (100%) rename {gstreamer-sys => sys/gstreamer-sys}/tests/layout.c (100%) rename {gstreamer-sys => sys/gstreamer-sys}/tests/manual.h (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/CHANGELOG.md (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/Cargo.toml (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/LICENSE (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/README.md (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/build.rs (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/src/lib.rs (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/tests/abi.rs (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/tests/constant.c (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/tests/layout.c (100%) rename {gstreamer-tag-sys => sys/gstreamer-tag-sys}/tests/manual.h (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/CHANGELOG.md (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/Cargo.toml (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/LICENSE (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/README.md (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/build.rs (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/src/lib.rs (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/tests/abi.rs (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/tests/constant.c (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/tests/layout.c (100%) rename {gstreamer-video-sys => sys/gstreamer-video-sys}/tests/manual.h (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/CHANGELOG.md (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/Cargo.toml (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/README.md (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/build.rs (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/src/lib.rs (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/tests/abi.rs (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/tests/constant.c (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/tests/layout.c (100%) rename {gstreamer-webrtc-sys => sys/gstreamer-webrtc-sys}/tests/manual.h (100%) diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index d4e793287..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "gir"] - path = gir - url = https://github.com/gtk-rs/gir diff --git a/gir b/gir deleted file mode 160000 index ad40c013c..000000000 --- a/gir +++ /dev/null @@ -1 +0,0 @@ -Subproject commit ad40c013c4745a5a8ed311022d76e6385ff134b8 diff --git a/gir-files/GES-1.0.gir b/gir-files/GES-1.0.gir deleted file mode 100644 index 6e4d9bb7f..000000000 --- a/gir-files/GES-1.0.gir +++ /dev/null @@ -1,16022 +0,0 @@ - - - - - - - - - - - - - A datatype to hold a frame number. - - - - - A #GESAsset in the GStreamer Editing Services represents a resources -that can be used. In particular, any class that implements the -#GESExtractable interface may have some associated assets with a -corresponding #GESAsset:extractable-type, from which its objects can be -extracted using ges_asset_extract(). Some examples would be -#GESClip, #GESFormatter and #GESTrackElement. - -All assets that are created within GES are stored in a cache; one per -each #GESAsset:id and #GESAsset:extractable-type pair. These assets can -be fetched, and initialized if they do not yet exist in the cache, -using ges_asset_request(). - -``` c -GESAsset *effect_asset; -GESEffect *effect; - -// You create an asset for an effect -effect_asset = ges_asset_request (GES_TYPE_EFFECT, "agingtv", NULL); - -// And now you can extract an instance of GESEffect from that asset -effect = GES_EFFECT (ges_asset_extract (effect_asset)); - -``` - -The advantage of using assets, rather than simply creating the object -directly, is that the currently loaded resources can be listed with -ges_list_assets() and displayed to an end user. For example, to show -which media files have been loaded, and a standard list of effects. In -fact, the GES library already creates assets for #GESTransitionClip and -#GESFormatter, which you can use to list all the available transition -types and supported formats. - -The other advantage is that #GESAsset implements #GESMetaContainer, so -metadata can be set on the asset, with some subclasses automatically -creating this metadata on initiation. - -For example, to display information about the supported formats, you -could do the following: -|[ - GList *formatter_assets, *tmp; - - // List all the transitions - formatter_assets = ges_list_assets (GES_TYPE_FORMATTER); - - // Print some infos about the formatter GESAsset - for (tmp = formatter_assets; tmp; tmp = tmp->next) { - g_print ("Name of the formatter: %s, file extension it produces: %s", - ges_meta_container_get_string ( - GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_NAME), - ges_meta_container_get_string ( - GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_EXTENSION)); - } - - g_list_free (transition_assets); - -]| - -## ID - -Each asset is uniquely defined in the cache by its -#GESAsset:extractable-type and #GESAsset:id. Depending on the -#GESAsset:extractable-type, the #GESAsset:id can be used to parametrise -the creation of the object upon extraction. By default, a class that -implements #GESExtractable will only have a single associated asset, -with an #GESAsset:id set to the type name of its objects. However, this -is overwritten by some implementations, which allow a class to have -multiple associated assets. For example, for #GESTransitionClip the -#GESAsset:id will be a nickname of the #GESTransitionClip:vtype. You -should check the documentation for each extractable type to see if they -differ from the default. - -Moreover, each #GESAsset:extractable-type may also associate itself -with a specific asset subclass. In such cases, when their asset is -requested, an asset of this subclass will be returned instead. - -## Managing - -You can use a #GESProject to easily manage the assets of a -#GESTimeline. - -## Proxies - -Some assets can (temporarily) act as the #GESAsset:proxy of another -asset. When the original asset is requested from the cache, the proxy -will be returned in its place. This can be useful if, say, you want -to substitute a #GESUriClipAsset corresponding to a high resolution -media file with the asset of a lower resolution stand in. - -An asset may even have several proxies, the first of which will act as -its default and be returned on requests, but the others will be ordered -to take its place once it is removed. You can add a proxy to an asset, -or set its default, using ges_asset_set_proxy(), and you can remove -them with ges_asset_unproxy(). - - - - - - Indicate that an existing #GESAsset in the cache should be reloaded -upon the next request. This can be used when some condition has -changed, which may require that an existing asset should be updated. -For example, if an external resource has changed or now become -available. - -Note, the asset is not immediately changed, but will only actually -reload on the next call to ges_asset_request() or -ges_asset_request_async(). - - - %TRUE if the specified asset exists in the cache and could be -marked for reloading. - - - - - The #GESAsset:extractable-type of the asset that -needs reloading - - - - The #GESAsset:id of the asset asset that needs -reloading - - - - - - Returns an asset with the given properties. If such an asset already -exists in the cache (it has been previously created in GES), then a -reference to the existing asset is returned. Otherwise, a newly created -asset is returned, and also added to the cache. - -If the requested asset has been loaded with an error, then @error is -set, if given, and %NULL will be returned instead. - -Note that the given @id may not be exactly the #GESAsset:id that is -set on the returned asset. For instance, it may be adjusted into a -standard format. Or, if a #GESExtractable type does not have its -extraction parametrised, as is the case by default, then the given @id -may be ignored entirely and the #GESAsset:id set to some standard, in -which case a %NULL @id can be given. - -Similarly, the given @extractable_type may not be exactly the -#GESAsset:extractable-type that is set on the returned asset. Instead, -the actual extractable type may correspond to a subclass of the given -@extractable_type, depending on the given @id. - -Moreover, depending on the given @extractable_type, the returned asset -may belong to a subclass of #GESAsset. - -Finally, if the requested asset has a #GESAsset:proxy, then the proxy -that is found at the end of the chain of proxies is returned (a proxy's -proxy will take its place, and so on, unless it has no proxy). - -Some asset subclasses only support asynchronous construction of its -assets, such as #GESUriClip. For such assets this method will fail, and -you should use ges_asset_request_async() instead. In the case of -#GESUriClip, you can use ges_uri_clip_asset_request_sync() if you only -want to wait for the request to finish. - - - A reference to the requested -asset, or %NULL if an error occurred. - - - - - The #GESAsset:extractable-type of the asset - - - - The #GESAsset:id of the asset - - - - - - Requests an asset with the given properties asynchronously (see -ges_asset_request()). When the asset has been initialized or fetched -from the cache, the given callback function will be called. The -asset can then be retrieved in the callback using the -ges_asset_request_finish() method on the given #GAsyncResult. - -Note that the source object passed to the callback will be the -#GESAsset corresponding to the request, but it may not have loaded -correctly and therefore can not be used as is. Instead, -ges_asset_request_finish() should be used to fetch a usable asset, or -indicate that an error occurred in the asset's creation. - -Note that the callback will be called in the #GMainLoop running under -the same #GMainContext that ges_init() was called in. So, if you wish -the callback to be invoked outside the default #GMainContext, you can -call g_main_context_push_thread_default() in a new thread before -calling ges_init(). - -Example of an asynchronous asset request: -``` c -// The request callback -static void -asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data) -{ - GESAsset *asset; - GError *error = NULL; - - asset = ges_asset_request_finish (res, &error); - if (asset) { - g_print ("The file: %s is usable as a GESUriClip", - ges_asset_get_id (asset)); - } else { - g_print ("The file: %s is *not* usable as a GESUriClip because: %s", - ges_asset_get_id (source), error->message); - } - - gst_object_unref (asset); -} - -// The request: -ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL, - (GAsyncReadyCallback) asset_loaded_cb, user_data); -``` - - - - - - - The #GESAsset:extractable-type of the asset - - - - The #GESAsset:id of the asset - - - - An object to allow cancellation of the -asset request, or %NULL to ignore - - - - A function to call when the initialization is finished - - - - Data to be passed to @callback - - - - - - Fetches an asset requested by ges_asset_request_async(), which -finalises the request. - - - The requested asset, or %NULL if an error -occurred. - - - - - The task result to fetch the asset from - - - - - - Extracts a new #GESAsset:extractable-type object from the asset. The -#GESAsset:id of the asset may determine the properties and state of the -newly created object. - - - A newly created object, or %NULL if an -error occurred. - - - - - The #GESAsset to extract an object from - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extracts a new #GESAsset:extractable-type object from the asset. The -#GESAsset:id of the asset may determine the properties and state of the -newly created object. - - - A newly created object, or %NULL if an -error occurred. - - - - - The #GESAsset to extract an object from - - - - - - Retrieve the error that was set on the asset when it was loaded. - - - The error set on @asset, or -%NULL if no error occurred when @asset was loaded. - - - - - A #GESAsset - - - - - - Gets the #GESAsset:extractable-type of the asset. - - - The extractable type of @self. - - - - - The #GESAsset - - - - - - Gets the #GESAsset:id of the asset. - - - The ID of @self. - - - - - A #GESAsset - - - - - - Gets the default #GESAsset:proxy of the asset. - - - The default proxy of @asset. - - - - - A #GESAsset - - - - - - Gets the #GESAsset:proxy-target of the asset. - -Note that the proxy target may have loaded with an error, so you should -call ges_asset_get_error() on the returned target. - - - The asset that @proxy is a proxy -of. - - - - - A #GESAsset - - - - - - Get all the proxies that the asset has. The first item of the list will -be the default #GESAsset:proxy. The second will be the proxy that is -'next in line' to be default, and so on. - - - The list of proxies -that @asset has. - - - - - - - A #GESAsset - - - - - - Sets the #GESAsset:proxy for the asset. - -If @proxy is among the existing proxies of the asset (see -ges_asset_list_proxies()) it will be moved to become the default -proxy. Otherwise, if @proxy is not %NULL, it will be added to the list -of proxies, as the new default. The previous default proxy will become -'next in line' for if the new one is removed, and so on. As such, this -will **not** actually remove the previous default proxy (use -ges_asset_unproxy() for that). - -Note that an asset can only act as a proxy for one other asset. - -As a special case, if @proxy is %NULL, then this method will actually -remove **all** proxies from the asset. - - - %TRUE if @proxy was successfully set as the default for -@asset. - - - - - The #GESAsset to proxy - - - - A new default proxy for @asset - - - - - - Removes the proxy from the available list of proxies for the asset. If -the given proxy is the default proxy of the list, then the next proxy -in the available list (see ges_asset_list_proxies()) will become the -default. If there are no other proxies, then the asset will no longer -have a default #GESAsset:proxy. - - - %TRUE if @proxy was successfully removed from @asset's proxy -list. - - - - - The #GESAsset to no longer proxy with @proxy - - - - An existing proxy of @asset - - - - - - The #GESExtractable object type that can be extracted from the asset. - - - - The ID of the asset. This should be unique amongst all assets with -the same #GESAsset:extractable-type. Depending on the associated -#GESExtractable implementation, this id may convey some information -about the #GObject that should be extracted. Note that, as such, the -ID will have an expected format, and you can not choose this value -arbitrarily. By default, this will be set to the type name of the -#GESAsset:extractable-type, but you should check the documentation -of the extractable type to see whether they differ from the -default behaviour. - - - - The default proxy for this asset, or %NULL if it has no proxy. A -proxy will act as a substitute for the original asset when the -original is requested (see ges_asset_request()). - -Setting this property will not usually remove the existing proxy, but -will replace it as the default (see ges_asset_set_proxy()). - - - - The asset that this asset is a proxy for, or %NULL if it is not a -proxy for another asset. - -Note that even if this asset is acting as a proxy for another asset, -but this asset is not the default #GESAsset:proxy, then @proxy-target -will *still* point to this other asset. So you should check the -#GESAsset:proxy property of @target-proxy before assuming it is the -current default proxy for the target. - -Note that the #GObject::notify for this property is emitted after -the #GESAsset:proxy #GObject::notify for the corresponding (if any) -asset it is now the proxy of/no longer the proxy of. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A newly created object, or %NULL if an -error occurred. - - - - - The #GESAsset to extract an object from - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Indicates that an error occurred - - - Indicates that the loading is being performed -asynchronously - - - Indicates that the loading is complete, without -error - - - - - - - ## Children Properties - -You can use the following children properties through the -#ges_track_element_set_child_property and alike set of methods: - -- #gdouble `volume`: volume factor, 1.0=100%. -- #gboolean `mute`: mute channel. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Outputs a test audio stream using audiotestsrc. The default property values -output silence. Useful for testing pipelines, or to fill gaps in an audio -track. - - - - - Get the current frequency of @self. - - - The current frequency of @self. - - - - - a #GESAudioTestSource - - - - - - Get the current volume of @self. - - - The current volume of @self - - - - - a #GESAudioTestSource - - - - - - Lets you set the frequency applied on the track element - - - - - - - a #GESAudioTestSource - - - - The frequency you want to apply on @self - - - - - - Sets the volume of the test audio signal. - - - - - - - a #GESAudioTestSource - - - - The volume you want to apply on @self - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESAudioTrack is a default audio #GESTrack, with a -#GES_TRACK_TYPE_AUDIO #GESTrack:track-type and "audio/x-raw(ANY)" -#GESTrack:caps. - -By default, an audio track will have its #GESTrack:restriction-caps -set to "audio/x-raw" with the following properties: - -- format: "S32LE" -- channels: 2 -- rate: 44100 -- layout: "interleaved" - -These fields are needed for negotiation purposes, but you can change -their values if you wish. It is advised that you do so using -ges_track_update_restriction_caps() with new values for the fields you -wish to change, and any additional fields you may want to add. Unlike -using ges_track_set_restriction_caps(), this will ensure that these -default fields will at least have some value set. - - - - - Creates a new audio track, with a #GES_TRACK_TYPE_AUDIO -#GESTrack:track-type, "audio/x-raw(ANY)" #GESTrack:caps, and -"audio/x-raw" #GESTrack:restriction-caps with the properties: - -- format: "S32LE" -- channels: 2 -- rate: 44100 -- layout: "interleaved" - -You should use ges_track_update_restriction_caps() if you wish to -modify these fields, or add additional ones. - - - The newly created audio track. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a new #GESAudioTransition. - This should never be called by applications as this will -be created by clips. - - - The newly created #GESAudioTransition. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ### Children Properties - - {{ libs/GESVideoUriSource-children-props.md }} - - - - - The location of the file/resource to use. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESBaseEffect is some operation that applies an effect to the data -it receives. - -## Time Effects - -Some operations will change the timing of the stream data they receive -in some way. In particular, the #GstElement that they wrap could alter -the times of the segment they receive in a #GST_EVENT_SEGMENT event, -or the times of a seek they receive in a #GST_EVENT_SEEK event. Such -operations would be considered time effects since they translate the -times they receive on their source to different times at their sink, -and vis versa. This introduces two sets of time coordinates for the -event: (internal) sink coordinates and (internal) source coordinates, -where segment times are translated from the sink coordinates to the -source coordinates, and seek times are translated from the source -coordinates to the sink coordinates. - -If you use such an effect in GES, you will need to inform GES of the -properties that control the timing with -ges_base_effect_register_time_property(), and the effect's timing -behaviour using ges_base_effect_set_time_translation_funcs(). - -Note that a time effect should not have its -#GESTrackElement:has-internal-source set to %TRUE. - -In addition, note that GES only *fully* supports time effects whose -mapping from the source to sink coordinates (those applied to seeks) -obeys: - -+ Maps the time `0` to `0`. So initial time-shifting effects are - excluded. -+ Is monotonically increasing. So reversing effects, and effects that - jump backwards in the stream are excluded. -+ Can handle a reasonable #GstClockTime, relative to the project. So - this would exclude a time effect with an extremely large speed-up - that would cause the converted #GstClockTime seeks to overflow. -+ Is 'continuously reversible'. This essentially means that for every - time in the sink coordinates, we can, to 'good enough' accuracy, - calculate the corresponding time in the source coordinates. Moreover, - this should correspond to how segment times are translated from - sink to source. -+ Only depends on the registered time properties, rather than the - state of the #GstElement or the data it receives. This would exclude, - say, an effect that would speedup if there is more red in the image - it receives. - -Note that a constant-rate-change effect that is not extremely fast or -slow would satisfy these conditions. For such effects, you may wish to -use ges_effect_class_register_rate_property(). - - - - - Get whether the effect is considered a time effect or not. An effect -with registered time properties or set translation functions is -considered a time effect. - - - %TRUE if @effect is considered a time effect. - - - - - A #GESBaseEffect - - - - - - Register a child property of the effect as a property that, when set, -can change the timing of its input data. The child property should be -specified as in ges_timeline_element_lookup_child(). - -You should also set the corresponding time translation using -ges_base_effect_set_time_translation_funcs(). - -Note that @effect must not be part of a clip, nor can it have -#GESTrackElement:has-internal-source set to %TRUE. - - - %TRUE if the child property was found and newly registered. - - - - - A #GESBaseEffect - - - - The name of the child property to register as -a time property - - - - - - Set the time translation query functions for the time effect. If an -effect is a time effect, it will have two sets of coordinates: one -at its sink and one at its source. The given functions should be able -to translate between these two sets of coordinates. More specifically, -@source_to_sink_func should *emulate* how the corresponding #GstElement -would translate the #GstSegment @time field, and @sink_to_source_func -should emulate how the corresponding #GstElement would translate the -seek query @start and @stop values, as used in gst_element_seek(). As -such, @sink_to_source_func should act as an approximate reverse of -@source_to_sink_func. - -Note, these functions will be passed a table of time properties, as -registered in ges_base_effect_register_time_property(), and their -values. The functions should emulate what the translation *would* be -*if* the time properties were set to the given values. They should not -use the currently set values. - -Note that @effect must not be part of a clip, nor can it have -#GESTrackElement:has-internal-source set to %TRUE. - - - %TRUE if the translation functions were set. - - - - - A #GESBaseEffect - - - - The function to use -for querying how a time is translated from the source coordinates to -the sink coordinates of @effect - - - - The function to use -for querying how a time is translated from the sink coordinates to the -source coordinates of @effect - - - - Data to pass to both @source_to_sink_func and -@sink_to_source_func - - - - Method to call to destroy -@user_data, or %NULL - - - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - #GESBaseEffectClip-s are clips whose core elements are -#GESBaseEffect-s. - -## Effects - -#GESBaseEffectClip-s can have **additional** #GESBaseEffect-s added as -non-core elements. These additional effects are applied to the output -of the core effects of the clip that they share a #GESTrack with. See -#GESClip for how to add and move these effects from the clip. - -Note that you cannot add time effects to #GESBaseEffectClip, neither -as core children, nor as additional effects. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A function for querying how an effect would translate a time if it had -the given child property values set. The keys for @time_properties will -be the same string that was passed to -ges_base_effect_register_time_property(), the values will be #GValue* -values of the corresponding child properties. You should always use the -values given in @time_properties before using the currently set values. - - - The translated time. - - - - - The #GESBaseEffect that is doing the time translation - - - - The #GstClockTime to translation - - - - A table of child -property name/value pairs - - - - - - - Data passed to ges_base_effect_set_time_translation_funcs() - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Whether the class allows for the user to add additional non-core -#GESBaseEffect-s to clips from this class. - - - - A #GESClipClass - - - - - The #GList containing the children of @obj. - - - - a #GESContainer - - - - - The #GESContainer:height of @obj. - - - - a #GESContainer - - - - - To be used by subclasses only. This indicate how to handle a change in -a child. - - - - - - - - - - - - - - #GESClip-s are the core objects of a #GESLayer. Each clip may exist in -a single layer but may control several #GESTrackElement-s that span -several #GESTrack-s. A clip will ensure that all its children share the -same #GESTimelineElement:start and #GESTimelineElement:duration in -their tracks, which will match the #GESTimelineElement:start and -#GESTimelineElement:duration of the clip itself. Therefore, changing -the timing of the clip will change the timing of the children, and a -change in the timing of a child will change the timing of the clip and -subsequently all its siblings. As such, a clip can be treated as a -singular object in its layer. - -For most uses of a #GESTimeline, it is often sufficient to only -interact with #GESClip-s directly, which will take care of creating and -organising the elements of the timeline's tracks. - -## Core Children - -In more detail, clips will usually have some *core* #GESTrackElement -children, which are created by the clip when it is added to a layer in -a timeline. The type and form of these core children will depend on the -clip's subclass. You can use ges_track_element_is_core() to determine -whether a track element is considered such a core track element. Note, -if a core track element is part of a clip, it will always be treated as -a core *child* of the clip. You can connect to the -#GESContainer::child-added signal to be notified of their creation. - -When a child is added to a clip, the timeline will select its tracks -using #GESTimeline::select-tracks-for-object. Note that it may be the -case that the child will still have no set #GESTrackElement:track -after this process. For example, if the timeline does not have a track -of the corresponding #GESTrack:track-type. A clip can safely contain -such children, which may have their track set later, although they will -play no functioning role in the timeline in the meantime. - -If a clip may create track elements with various -#GESTrackElement:track-type(s), such as a #GESUriClip, but you only -want it to create a subset of these types, you should set the -#GESClip:supported-formats of the clip to the subset of types. This -should be done *before* adding the clip to a layer. - -If a clip will produce several core elements of the same -#GESTrackElement:track-type, you should connect to the timeline's -#GESTimeline::select-tracks-for-object signal to coordinate which -tracks each element should land in. Note, no two core children within a -clip can share the same #GESTrack, so you should not select the same -track for two separate core children. Provided you stick to this rule, -it is still safe to select several tracks for the same core child, the -core child will be copied into the additional tracks. You can manually -add the child to more tracks later using ges_clip_add_child_to_track(). -If you do not wish to use a core child, you can always select no track. - -The #GESTimelineElement:in-point of the clip will control the -#GESTimelineElement:in-point of its core children to be the same -value if their #GESTrackElement:has-internal-source is set to %TRUE. - -The #GESTimelineElement:max-duration of the clip is the minimum -#GESTimelineElement:max-duration of its core children. If you set its -value to anything other than its current value, this will also set the -#GESTimelineElement:max-duration of all its core children to the same -value if their #GESTrackElement:has-internal-source is set to %TRUE. -As a special case, whilst a clip does not yet have any core children, -its #GESTimelineElement:max-duration may be set to indicate what its -value will be once they are created. - -## Effects - -Some subclasses (#GESSourceClip and #GESBaseEffectClip) may also allow -their objects to have additional non-core #GESBaseEffect-s elements as -children. These are additional effects that are applied to the output -data of the core elements. They can be added to the clip using -ges_clip_add_top_effect(), which will take care of adding the effect to -the timeline's tracks. The new effect will be placed between the clip's -core track elements and its other effects. As such, the newly added -effect will be applied to any source data **before** the other existing -effects. You can change the ordering of effects using -ges_clip_set_top_effect_index(). - -Tracks are selected for top effects in the same way as core children. -If you add a top effect to a clip before it is part of a timeline, and -later add the clip to a timeline, the track selection for the top -effects will occur just after the track selection for the core -children. If you add a top effect to a clip that is already part of a -timeline, the track selection will occur immediately. Since a top -effect must be applied on top of a core child, if you use -#GESTimeline::select-tracks-for-object, you should ensure that the -added effects are destined for a #GESTrack that already contains a core -child. - -In addition, if the core child in the track is not -#GESTrackElement:active, then neither can any of its effects be -#GESTrackElement:active. Therefore, if a core child is made in-active, -all of the additional effects in the same track will also become -in-active. Similarly, if an effect is set to be active, then the core -child will also become active, but other effects will be left alone. -Finally, if an active effect is added to the track of an in-active core -child, it will become in-active as well. Note, in contrast, setting a -core child to be active, or an effect to be in-active will *not* change -the other children in the same track. - -### Time Effects - -Some effects also change the timing of their data (see #GESBaseEffect -for what counts as a time effect). Note that a #GESBaseEffectClip will -refuse time effects, but a #GESSource will allow them. - -When added to a clip, time effects may adjust the timing of other -children in the same track. Similarly, when changing the order of -effects, making them (in)-active, setting their time property values -or removing time effects. These can cause the #GESClip:duration-limit -to change in value. However, if such an operation would ever cause the -#GESTimelineElement:duration to shrink such that a clip's #GESSource is -totally overlapped in the timeline, the operation would be prevented. -Note that the same can happen when adding non-time effects with a -finite #GESTimelineElement:max-duration. - -Therefore, when working with time effects, you should -- more so than -usual -- not assume that setting the properties of the clip's children -will succeed. In particular, you should use -ges_timeline_element_set_child_property_full() when setting the time -properties. - -If you wish to preserve the *internal* duration of a source in a clip -during these time effect operations, you can do something like the -following. - -```c -void -do_time_effect_change (GESClip * clip) -{ - GList *tmp, *children; - GESTrackElement *source; - GstClockTime source_outpoint; - GstClockTime new_end; - GError *error = NULL; - - // choose some active source in a track to preserve the internal - // duration of - source = ges_clip_get_track_element (clip, NULL, GES_TYPE_SOURCE); - - // note its current internal end time - source_outpoint = ges_clip_get_internal_time_from_timeline_time ( - clip, source, GES_TIMELINE_ELEMENT_END (clip), NULL); - - // handle invalid out-point - - // stop the children's control sources from clamping when their - // out-point changes with a change in the time effects - children = ges_container_get_children (GES_CONTAINER (clip), FALSE); - - for (tmp = children; tmp; tmp = tmp->next) - ges_track_element_set_auto_clamp_control_source (tmp->data, FALSE); - - // add time effect, or set their children properties, or move them around - ... - // user can make sure that if a time effect changes one source, we should - // also change the time effect for another source. E.g. if - // "GstVideorate::rate" is set to 2.0, we also set "GstPitch::rate" to - // 2.0 - - // Note the duration of the clip may have already changed if the - // duration-limit of the clip dropped below its current value - - new_end = ges_clip_get_timeline_time_from_internal_time ( - clip, source, source_outpoint, &error); - // handle error - - if (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip), - -1, GES_EDIT_MODE_TRIM, GES_EDGE_END, new_end, &error)) - // handle error - - for (tmp = children; tmp; tmp = tmp->next) - ges_track_element_set_auto_clamp_control_source (tmp->data, TRUE); - - g_list_free_full (children, gst_object_unref); - gst_object_unref (source); -} -``` - - - - - - - The #GESTrackElement created -by @clip, or %NULL if @clip can not provide a track element for the -given @type or an error occurred. - - - - - A #GESClip - - - - A #GESTrackType to create a #GESTrackElement for - - - - - - - - A list of -the #GESTrackElement-s created by @clip for the given @type, or %NULL -if no track elements are created or an error occurred. - - - - - - - A #GESClip - - - - A #GESTrackType to create #GESTrackElement-s for - - - - - - Extracts a #GESTrackElement from an asset and adds it to the clip. -This can be used to add effects that derive from the asset to the -clip, but this method is not intended to be used to create the core -elements of the clip. - - - The newly created element, or -%NULL if an error occurred. - - - - - A #GESClip - - - - An asset with #GES_TYPE_TRACK_ELEMENT as its -#GESAsset:extractable-type - - - - - - Adds the track element child of the clip to a specific track. - -If the given child is already in another track, this will create a copy -of the child, add it to the clip, and add this copy to the track. - -You should only call this whilst a clip is part of a #GESTimeline, and -for tracks that are in the same timeline. - -This method is an alternative to using the -#GESTimeline::select-tracks-for-object signal, but can be used to -complement it when, say, you wish to copy a clip's children from one -track into a new one. - -When the child is a core child, it must be added to a track that does -not already contain another core child of the same clip. If it is not a -core child (an additional effect), then it must be added to a track -that already contains one of the core children of the same clip. - -This method can also fail if the adding the track element to the track -would break a configuration rule of the corresponding #GESTimeline, -such as causing three sources to overlap at a single time, or causing -a source to completely overlap another in the same track. - - - The element that was added to @track, either -@child or a copy of child, or %NULL if the element could not be added. - - - - - A #GESClip - - - - A child of @clip - - - - The track to add @child to - - - - - - Add a top effect to a clip at the given index. - -Unlike using ges_container_add(), this allows you to set the index -in advance. It will also check that no error occurred during the track -selection for the effect. - -Note, only subclasses of #GESClipClass that have -#GES_CLIP_CLASS_CAN_ADD_EFFECTS set to %TRUE (such as #GESSourceClip -and #GESBaseEffectClip) can have additional top effects added. - -Note, if the effect is a time effect, this may be refused if the clip -would not be able to adapt itself once the effect is added. - - - %TRUE if @effect was successfully added to @clip at @index. - - - - - A #GESClip - - - - A top effect to add - - - - The index to add @effect at, or -1 to add at the highest - - - - - - Finds an element controlled by the clip. If @track is given, -then only the track elements in @track are searched for. If @type is -given, then this function searches for a track element of the given -@type. - -Note, if multiple track elements in the clip match the given criteria, -this will return the element amongst them with the highest -#GESTimelineElement:priority (numerically, the smallest). See -ges_clip_find_track_elements() if you wish to find all such elements. - - - The element controlled by -@clip, in @track, and of the given @type, or %NULL if no such element -could be found. - - - - - A #GESClip - - - - The track to search in, or %NULL to search in -all tracks - - - - The type of track element to search for, or `G_TYPE_NONE` to -match any type - - - - - - Finds the #GESTrackElement-s controlled by the clip that match the -given criteria. If @track is given as %NULL and @track_type is given as -#GES_TRACK_TYPE_UNKNOWN, then the search will match all elements in any -track, including those with no track, and of any -#GESTrackElement:track-type. Otherwise, if @track is not %NULL, but -@track_type is #GES_TRACK_TYPE_UNKNOWN, then only the track elements in -@track are searched for. Otherwise, if @track_type is not -#GES_TRACK_TYPE_UNKNOWN, but @track is %NULL, then only the track -elements whose #GESTrackElement:track-type matches @track_type are -searched for. Otherwise, when both are given, the track elements that -match **either** criteria are searched for. Therefore, if you wish to -only find elements in a specific track, you should give the track as -@track, but you should not give the track's #GESTrack:track-type as -@track_type because this would also select elements from other tracks -of the same type. - -You may also give @type to _further_ restrict the search to track -elements of the given @type. - - - A list of all -the #GESTrackElement-s controlled by @clip, in @track or of the given -@track_type, and of the given @type. - - - - - - - A #GESClip - - - - The track to search in, or %NULL to search in -all tracks - - - - The track-type of the track element to search for, or -#GES_TRACK_TYPE_UNKNOWN to match any track type - - - - The type of track element to search for, or %G_TYPE_NONE to -match any type - - - - - - Gets the #GESClip:duration-limit of the clip. - - - The duration-limit of @clip. - - - - - A #GESClip - - - - - - Convert the timeline time to an internal source time of the child. -This will take any time effects placed on the clip into account (see -#GESBaseEffect for what time effects are supported, and how to -declare them in GES). - -When @timeline_time is above the #GESTimelineElement:start of @clip, -this will return the internal time at which the content that appears at -@timeline_time in the output of the timeline is created in @child. For -example, if @timeline_time corresponds to the current seek position, -this would let you know which part of a media file is being read. - -This will be done assuming the clip has an indefinite end, so the -internal time may be beyond the current out-point of the child, or even -its #GESTimelineElement:max-duration. - -If, instead, @timeline_time is below the current -#GESTimelineElement:start of @clip, this will return what you would -need to set the #GESTimelineElement:in-point of @child to if you set -the #GESTimelineElement:start of @clip to @timeline_time and wanted -to keep the content of @child currently found at the current -#GESTimelineElement:start of @clip at the same timeline position. If -this would be negative, the conversion fails. This is useful for -determining what #GESTimelineElement:in-point would result from a -#GES_EDIT_MODE_TRIM to @timeline_time. - -Note that whilst a clip has no time effects, this second return is -equivalent to finding the internal time at which the content that -appears at @timeline_time in the timeline can be found in @child if it -had indefinite extent in both directions. However, with non-linear time -effects this second return will be more distinct. - -In either case, the returned time would be appropriate to use for the -#GESTimelineElement:in-point or #GESTimelineElement:max-duration of the -child. - -See ges_clip_get_timeline_time_from_internal_time(), which performs the -reverse. - - - The time in the internal coordinates of @child corresponding -to @timeline_time, or #GST_CLOCK_TIME_NONE if the conversion could not -be performed. - - - - - A #GESClip - - - - An #GESTrackElement:active child of @clip with a -#GESTrackElement:track - - - - A time in the timeline time coordinates - - - - - - Gets the #GESClip:layer of the clip. - - - The layer @clip is in, or %NULL if -@clip is not in any layer. - - - - - A #GESClip - - - - - - Gets the #GESClip:supported-formats of the clip. - - - The #GESTrackType-s supported by @clip. - - - - - A #GESClip - - - - - - Convert the internal source time from the child to a timeline time. -This will take any time effects placed on the clip into account (see -#GESBaseEffect for what time effects are supported, and how to -declare them in GES). - -When @internal_time is above the #GESTimelineElement:in-point of -@child, this will return the timeline time at which the internal -content found at @internal_time appears in the output of the timeline's -track. For example, this would let you know where in the timeline a -particular scene in a media file would appear. - -This will be done assuming the clip has an indefinite end, so the -timeline time may be beyond the end of the clip, or even breaking its -#GESClip:duration-limit. - -If, instead, @internal_time is below the current -#GESTimelineElement:in-point of @child, this will return what you would -need to set the #GESTimelineElement:start of @clip to if you set the -#GESTimelineElement:in-point of @child to @internal_time and wanted to -keep the content of @child currently found at the current -#GESTimelineElement:start of @clip at the same timeline position. If -this would be negative, the conversion fails. This is useful for -determining what position to use in a #GES_EDIT_MODE_TRIM if you wish -to trim to a specific point in the internal content, such as a -particular scene in a media file. - -Note that whilst a clip has no time effects, this second return is -equivalent to finding the timeline time at which the content of @child -at @internal_time would be found in the timeline if it had indefinite -extent in both directions. However, with non-linear time effects this -second return will be more distinct. - -In either case, the returned time would be appropriate to use in -ges_timeline_element_edit() for #GES_EDIT_MODE_TRIM, and similar, if -you wish to use a particular internal point as a reference. For -example, you could choose to end a clip at a certain internal -'out-point', similar to the #GESTimelineElement:in-point, by -translating the desired end time into the timeline coordinates, and -using this position to trim the end of a clip. - -See ges_clip_get_internal_time_from_timeline_time(), which performs the -reverse, or ges_clip_get_timeline_time_from_source_frame() which does -the same conversion, but using frame numbers. - - - The time in the timeline coordinates corresponding to -@internal_time, or #GST_CLOCK_TIME_NONE if the conversion could not be -performed. - - - - - A #GESClip - - - - An #GESTrackElement:active child of @clip with a -#GESTrackElement:track - - - - A time in the internal time coordinates of @child - - - - - - Convert the source frame number to a timeline time. This acts the same -as ges_clip_get_timeline_time_from_internal_time() using the core -children of the clip and using the frame number to specify the internal -position, rather than a timestamp. - -The returned timeline time can be used to seek or edit to a specific -frame. - -Note that you can get the frame timestamp of a particular clip asset -with ges_clip_asset_get_frame_time(). - - - The timestamp corresponding to @frame_number in the core -children of @clip, in the timeline coordinates, or #GST_CLOCK_TIME_NONE -if the conversion could not be performed. - - - - - A #GESClip - - - - The frame number to get the corresponding timestamp of -in the timeline coordinates - - - - - - Gets the internal index of an effect in the clip. The index of effects -in a clip will run from 0 to n-1, where n is the total number of -effects. If two effects share the same #GESTrackElement:track, the -effect with the numerically lower index will be applied to the source -data **after** the other effect, i.e. output data will always flow from -a higher index effect to a lower index effect. - - - The index of @effect in @clip, or -1 if something went wrong. - - - - - A #GESClip - - - - The effect we want to get the index of - - - - - - - - - - - - - - - - - - - - Gets the #GESBaseEffect-s that have been added to the clip. The -returned list is ordered by their internal index in the clip. See -ges_clip_get_top_effect_index(). - - - A list of all -#GESBaseEffect-s that have been added to @clip. - - - - - - - A #GESClip - - - - - - See ges_clip_move_to_layer_full(), which also gives an error. - - - %TRUE if @clip was successfully moved to @layer. - - - - - A #GESClip - - - - The new layer - - - - - - Moves a clip to a new layer. If the clip already exists in a layer, it -is first removed from its current layer before being added to the new -layer. - - - %TRUE if @clip was successfully moved to @layer. - - - - - A #GESClip - - - - The new layer - - - - - - Remove a top effect from the clip. - -Note, if the effect is a time effect, this may be refused if the clip -would not be able to adapt itself once the effect is removed. - - - %TRUE if @effect was successfully added to @clip at @index. - - - - - A #GESClip - - - - The top effect to remove - - - - - - Sets the #GESClip:supported-formats of the clip. This should normally -only be called by subclasses, which should be responsible for updating -its value, rather than the user. - - - - - - - A #GESClip - - - - The #GESTrackType-s supported by @clip - - - - - - See ges_clip_set_top_effect_index_full(), which also gives an error. - - - %TRUE if @effect was successfully moved to @newindex. - - - - - A #GESClip - - - - An effect within @clip to move - - - - The index for @effect in @clip - - - - - - Set the index of an effect within the clip. See -ges_clip_get_top_effect_index(). The new index must be an existing -index of the clip. The effect is moved to the new index, and the other -effects may be shifted in index accordingly to otherwise maintain the -ordering. - - - %TRUE if @effect was successfully moved to @newindex. - - - - - A #GESClip - - - - An effect within @clip to move - - - - The index for @effect in @clip - - - - - - - - - - - - - - - - - - - - - - - See ges_clip_split_full(), which also gives an error. - - - The newly created clip resulting -from the splitting @clip, or %NULL if @clip can't be split. - - - - - The #GESClip to split - - - - The timeline position at which to perform the split - - - - - - Splits a clip at the given timeline position into two clips. The clip -must already have a #GESClip:layer. - -The original clip's #GESTimelineElement:duration is reduced such that -its end point matches the split position. Then a new clip is created in -the same layer, whose #GESTimelineElement:start matches the split -position and #GESTimelineElement:duration will be set such that its end -point matches the old end point of the original clip. Thus, the two -clips together will occupy the same positions in the timeline as the -original clip did. - -The children of the new clip will be new copies of the original clip's -children, so it will share the same sources and use the same -operations. - -The new clip will also have its #GESTimelineElement:in-point set so -that any internal data will appear in the timeline at the same time. -Thus, when the timeline is played, the playback of data should -appear the same. This may be complicated by any additional -#GESEffect-s that have been placed on the original clip that depend on -the playback time or change the data consumption rate of sources. This -method will attempt to translate these effects such that the playback -appears the same. In such complex situations, you may get a better -result if you place the clip in a separate sub #GESProject, which only -contains this clip (and its effects), and in the original layer -create two neighbouring #GESUriClip-s that reference this sub-project, -but at a different #GESTimelineElement:in-point. - - - The newly created clip resulting -from the splitting @clip, or %NULL if @clip can't be split. - - - - - The #GESClip to split - - - - The timeline position at which to perform the split, between -the start and end of the clip - - - - - - The maximum #GESTimelineElement:duration that can be *currently* set -for the clip, taking into account the #GESTimelineElement:in-point, -#GESTimelineElement:max-duration, #GESTrackElement:active, and -#GESTrackElement:track properties of its children, as well as any -time effects. If there is no limit, this will be set to -#GST_CLOCK_TIME_NONE. - -Note that whilst a clip has no children in any tracks, the limit will -be unknown, and similarly set to #GST_CLOCK_TIME_NONE. - -If the duration-limit would ever go below the current -#GESTimelineElement:duration of the clip due to a change in the above -variables, its #GESTimelineElement:duration will be set to the new -limit. - - - - The layer this clip lies in. - -If you want to connect to this property's #GObject::notify signal, -you should connect to it with g_signal_connect_after() since the -signal emission may be stopped internally. - - - - The #GESTrackType-s that the clip supports, which it can create -#GESTrackElement-s for. Note that this can be a combination of -#GESTrackType flags to indicate support for several -#GESTrackElement:track-type elements. - - - - - - - - - - - - - - - - The #GESUriClipAsset is a special #GESAsset specilized in #GESClip. -it is mostly used to get information about the #GESTrackType-s the objects extracted -from it can potentialy create #GESTrackElement for. - - - - - - Result: %TRUE if @self has a natural framerate %FALSE otherwise - - - %TRUE if @self has a natural framerate @FALSE otherwise. - - - - - The object from which to retrieve the natural framerate - - - - The framerate numerator - - - - The framerate denominator - - - - - - Converts the given frame number into a timestamp, using the "natural" frame -rate of the asset. - -You can use this to reference a specific frame in a media file and use this -as, for example, the `in-point` or `max-duration` of a #GESClip. - - - The timestamp corresponding to @frame_number in the element source, given -in internal time coordinates, or #GST_CLOCK_TIME_NONE if the clip asset does not have a -natural frame rate. - - - - - The object for which to compute timestamp for specifed frame - - - - The frame number we want the internal time coordinate timestamp of - - - - - - Result: %TRUE if @self has a natural framerate %FALSE otherwise - - - - - - - The object from which to retrieve the natural framerate - - - - The framerate numerator - - - - The framerate denominator - - - - - - Gets track types for which objects extracted from @self can create #GESTrackElement - - - The track types on which @self will create TrackElement when added to -a layer - - - - - a #GESClipAsset - - - - - - Sets track types for which objects extracted from @self can create #GESTrackElement - - - - - - - a #GESClipAsset - - - - The track types supported by the GESClipAsset - - - - - - The formats supported by the asset. - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if @self has a natural framerate @FALSE otherwise. - - - - - The object from which to retrieve the natural framerate - - - - The framerate numerator - - - - The framerate denominator - - - - - - - - - - - - - - - - - - - - - Method to create the core #GESTrackElement of -a clip of this class. If a clip of this class may create several track -elements per track type, this should be left as %NULL, and -create_track_elements() should be used instead. Otherwise, you should -implement this class method and leave create_track_elements() as the -default implementation - - - - Method to create the (multiple) core -#GESTrackElement-s of a clip of this class. If create_track_element() -is implemented, this should be kept as the default implementation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESContainer is a timeline element that controls other -#GESTimelineElement-s, which are its children. In particular, it is -responsible for maintaining the relative #GESTimelineElement:start and -#GESTimelineElement:duration times of its children. Therefore, if a -container is temporally adjusted or moved to a new layer, it may -accordingly adjust and move its children. Similarly, a change in one of -its children may prompt the parent to correspondingly change its -siblings. - - - - - Groups the containers into a single container by merging them. The -containers must all belong to the same #GESTimelineElement:timeline. - -If the elements are all #GESClip-s then this method will attempt to -combine them all into a single #GESClip. This should succeed if they: -share the same #GESTimelineElement:start, #GESTimelineElement:duration -and #GESTimelineElement:in-point; exist in the same layer; and all of -the sources share the same #GESAsset. If this fails, or one of the -elements is not a #GESClip, this method will try to create a #GESGroup -instead. - - - The container created by merging -@containers, or %NULL if they could not be merged into a single -container. - - - - - -The #GESContainer-s to group - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Edits the container within its timeline. - use #ges_timeline_element_edit instead. - - - %TRUE if the edit of @container completed, %FALSE on failure. - - - - - The #GESContainer to edit - - - - A whitelist of layers -where the edit can be performed, %NULL allows all layers in the -timeline - - - - - - The priority/index of the layer @container should -be moved to. -1 means no move - - - - The edit mode - - - - The edge of @container where the edit should occur - - - - The edit position: a new location for the edge of @container -(in nanoseconds) - - - - - - - - - - - - - - - - - - - - Ungroups the container by splitting it into several containers -containing various children of the original. The rules for how the -container splits depends on the subclass. A #GESGroup will simply split -into its children. A #GESClip will split into one #GESClip per -#GESTrackType it overlaps with (so an audio-video clip will split into -an audio clip and a video clip), where each clip contains all the -#GESTrackElement-s from the original clip with a matching -#GESTrackElement:track-type. - -If @recursive is %TRUE, and the container contains other containers as -children, then they will also be ungrouped, and so on. - - - The list of -new #GESContainer-s created from the splitting of @container. - - - - - - - The container to ungroup - - - - Whether to recursively ungroup @container - - - - - - Adds a timeline element to the container. The element will now be a -child of the container (and the container will be the -#GESTimelineElement:parent of the added element), which means that it -is now controlled by the container. This may change the properties of -the child or the container, depending on the subclass. - -Additionally, the children properties of the newly added element will -be shared with the container, meaning they can also be read and set -using ges_timeline_element_get_child_property() and -ges_timeline_element_set_child_property() on the container. - - - %TRUE if @child was successfully added to @container. - - - - - A #GESContainer - - - - The element to add as a child - - - - - - Edits the container within its timeline. - use #ges_timeline_element_edit instead. - - - %TRUE if the edit of @container completed, %FALSE on failure. - - - - - The #GESContainer to edit - - - - A whitelist of layers -where the edit can be performed, %NULL allows all layers in the -timeline - - - - - - The priority/index of the layer @container should -be moved to. -1 means no move - - - - The edit mode - - - - The edge of @container where the edit should occur - - - - The edit position: a new location for the edge of @container -(in nanoseconds) - - - - - - Get the list of timeline elements contained in the container. If -@recursive is %TRUE, and the container contains other containers as -children, then their children will be added to the list, in addition to -themselves, and so on. - - - The list of -#GESTimelineElement-s contained in @container. - - - - - - - A #GESContainer - - - - Whether to recursively get children in @container - - - - - - Removes a timeline element from the container. The element will no -longer be controlled by the container. - - - %TRUE if @child was successfully removed from @container. - - - - - A #GESContainer - - - - The child to remove - - - - - - Ungroups the container by splitting it into several containers -containing various children of the original. The rules for how the -container splits depends on the subclass. A #GESGroup will simply split -into its children. A #GESClip will split into one #GESClip per -#GESTrackType it overlaps with (so an audio-video clip will split into -an audio clip and a video clip), where each clip contains all the -#GESTrackElement-s from the original clip with a matching -#GESTrackElement:track-type. - -If @recursive is %TRUE, and the container contains other containers as -children, then they will also be ungrouped, and so on. - - - The list of -new #GESContainer-s created from the splitting of @container. - - - - - - - The container to ungroup - - - - Whether to recursively ungroup @container - - - - - - The span of the container's children's #GESTimelineElement:priority -values, which is the number of integers that lie between (inclusive) -the minimum and maximum priorities found amongst the container's -children (maximum - minimum + 1). - - - - - - - The list of -#GESTimelineElement-s controlled by this Container - - - - - - The #GESContainer:height of @obj - - - - - - - - - - - - - - - - - - Will be emitted after a child is added to the container. Usually, -you should connect with g_signal_connect_after() since the signal -may be stopped internally. - - - - - - The child that was added - - - - - - Will be emitted after a child is removed from the container. - - - - - - The child that was removed - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The list of -new #GESContainer-s created from the splitting of @container. - - - - - - - The container to ungroup - - - - Whether to recursively ungroup @container - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the edit of @container completed, %FALSE on failure. - - - - - The #GESContainer to edit - - - - A whitelist of layers -where the edit can be performed, %NULL allows all layers in the -timeline - - - - - - The priority/index of the layer @container should -be moved to. -1 means no move - - - - The edit mode - - - - The edge of @container where the edit should occur - - - - The edit position: a new location for the edge of @container -(in nanoseconds) - - - - - - - - - - - - - - - - - - - A function that creates a #GstElement that can be used as a source to -fill the gaps of the track. A gap is a timeline region where the track -has no #GESTrackElement sources. - - - A source #GstElement to fill gaps in @track. - - - - - The #GESTrack - - - - - - A method for creating the core #GESTrackElement of a clip, to be added -to a #GESTrack of the given track type. - -If a clip may produce several track elements per track type, -#GESCreateTrackElementsFunc is more appropriate. - - - The #GESTrackElement created -by @clip, or %NULL if @clip can not provide a track element for the -given @type or an error occurred. - - - - - A #GESClip - - - - A #GESTrackType to create a #GESTrackElement for - - - - - - A method for creating the core #GESTrackElement-s of a clip, to be -added to #GESTrack-s of the given track type. - - - A list of -the #GESTrackElement-s created by @clip for the given @type, or %NULL -if no track elements are created or an error occurred. - - - - - - - A #GESClip - - - - A #GESTrackType to create #GESTrackElement-s for - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The edges of an object contain in a #GESTimeline or #GESTrack - - - Represents the start of an object. - - - - Represents the end of an object. - - - - Represent the fact we are not working with any edge of an - object. - - - - - A human friendly name for @edge - - - - - The #GESEdge to get the name of - - - - - - - When a single timeline element is edited within its timeline at some -position, using ges_timeline_element_edit(), depending on the edit -mode, its #GESTimelineElement:start, #GESTimelineElement:duration or -#GESTimelineElement:in-point will be adjusted accordingly. In addition, -any clips may change #GESClip:layer. - -Each edit can be broken down into a combination of three basic edits: - -+ MOVE: This moves the start of the element to the edit position. -+ START-TRIM: This cuts or grows the start of the element, whilst - maintaining the time at which its internal content appears in the - timeline data output. If the element is made shorter, the data that - appeared at the edit position will still appear in the timeline at - the same time. If the element is made longer, the data that appeared - at the previous start of the element will still appear in the - timeline at the same time. -+ END-TRIM: Similar to START-TRIM, but the end of the element is cut or - grown. - -In particular, when editing a #GESClip: - -+ MOVE: This will set the #GESTimelineElement:start of the clip to the - edit position. -+ START-TRIM: This will set the #GESTimelineElement:start of the clip - to the edit position. To keep the end time the same, the - #GESTimelineElement:duration of the clip will be adjusted in the - opposite direction. In addition, the #GESTimelineElement:in-point of - the clip will be shifted such that the content that appeared at the - new or previous start time, whichever is latest, still appears at the - same timeline time. For example, if a frame appeared at the start of - the clip, and the start of the clip is reduced, the in-point of the - clip will also reduce such that the frame will appear later within - the clip, but at the same timeline position. -+ END-TRIM: This will set the #GESTimelineElement:duration of the clip - such that its end time will match the edit position. - -When editing a #GESGroup: - -+ MOVE: This will set the #GESGroup:start of the clip to the edit - position by shifting all of its children by the same amount. So each - child will maintain their relative positions. -+ START-TRIM: If the group is made shorter, this will START-TRIM any - clips under the group that start after the edit position to the same - edit position. If the group is made longer, this will START-TRIM any - clip under the group whose start matches the start of the group to - the same edit position. -+ END-TRIM: If the group is made shorter, this will END-TRIM any clips - under the group that end after the edit position to the same edit - position. If the group is made longer, this will END-TRIM any clip - under the group whose end matches the end of the group to the same - edit position. - -When editing a #GESTrackElement, if it has a #GESClip parent, this -will be edited instead. Otherwise it is edited in the same way as a -#GESClip. - -The layer priority of a #GESGroup is the lowest layer priority of any -#GESClip underneath it. When a group is edited to a new layer -priority, it will shift all clips underneath it by the same amount, -such that their relative layers stay the same. - -If the #GESTimeline has a #GESTimeline:snapping-distance, then snapping -may occur for some of the edges of the **main** edited element: - -+ MOVE: The start or end edge of *any* #GESSource under the element may - be snapped. -+ START-TRIM: The start edge of a #GESSource whose start edge touches - the start edge of the element may snap. -+ END-TRIM: The end edge of a #GESSource whose end edge touches the end - edge of the element may snap. - -These edges may snap with either the start or end edge of *any* other -#GESSource in the timeline that is not also being moved by the element, -including those in different layers, if they are within the -#GESTimeline:snapping-distance. During an edit, only up to one snap can -occur. This will shift the edit position such that the snapped edges -will touch once the edit has completed. - -Note that snapping can cause an edit to fail where it would have -otherwise succeeded because it may push the edit position such that the -edit would result in an unsupported timeline configuration. Similarly, -snapping can cause an edit to succeed where it would have otherwise -failed. - -For example, in #GES_EDIT_MODE_RIPPLE acting on #GES_EDGE_NONE, the -main element is the MOVED toplevel of the edited element. Any source -under the main MOVED toplevel may have its start or end edge snapped. -Note, these sources cannot snap with each other. The edit may also -push other elements, but any sources under these elements cannot snap, -nor can they be snapped with. If a snap does occur, the MOVE of the -toplevel *and* all other elements pushed by the ripple will be shifted -by the same amount such that the snapped edges will touch. - -You can also find more explanation about the behaviour of those modes at: -[trim, ripple and roll](http://pitivi.org/manual/trimming.html) -and [clip management](http://pitivi.org/manual/usingclips.html). - - - The element is edited the normal way (default). - If acting on the element as a whole (#GES_EDGE_NONE), this will MOVE - the element by MOVING its toplevel. When acting on the start of the - element (#GES_EDGE_START), this will only MOVE the element, but not - its toplevel parent. This can allow you to move a #GESClip or - #GESGroup to a new start time or layer within its container group, - without effecting other members of the group. When acting on the end - of the element (#GES_EDGE_END), this will END-TRIM the element, - leaving its toplevel unchanged. - - - - The element is edited in ripple mode: moving - itself as well as later elements, keeping their relative times. This - edits the element the same as #GES_EDIT_MODE_NORMAL. In addition, if - acting on the element as a whole, or the start of the element, any - toplevel element in the same timeline (including different layers) - whose start time is later than the *current* start time of the MOVED - element will also be MOVED by the same shift as the edited element. - If acting on the end of the element, any toplevel element whose start - time is later than the *current* end time of the edited element will - also be MOVED by the same shift as the change in the end of the - edited element. These additional elements will also be shifted by - the same shift in layers as the edited element. - - - - The element is edited in roll mode: swapping its - content for its neighbour's, or vis versa, in the timeline output. - This edits the element the same as #GES_EDIT_MODE_TRIM. In addition, - any neighbours are also TRIMMED at their opposite edge to the same - timeline position. When acting on the start of the element, a - neighbour is any earlier element in the timeline whose end time - matches the *current* start time of the edited element. When acting on - the end of the element, a neighbour is any later element in the - timeline whose start time matches the *current* start time of the - edited element. In addition, a neighbour have a #GESSource at its - end/start edge that shares a track with a #GESSource at the start/end - edge of the edited element. Basically, a neighbour is an element that - can be extended, or cut, to have its content replace, or be replaced - by, the content of the edited element. Acting on the element as a - whole (#GES_EDGE_NONE) is not defined. The element can not shift - layers under this mode. - - - - The element is edited in trim mode. When acting - on the start of the element, this will START-TRIM it. When acting on - the end of the element, this will END-TRIM it. Acting on the element - as a whole (#GES_EDGE_NONE) is not defined. - - - - The element is edited in slide mode (not yet - implemented): moving the element replacing or consuming content on - each end. When acting on the element as a whole, this will MOVE the - element, and TRIM any neighbours on either side. A neighbour is - defined in the same way as in #GES_EDIT_MODE_ROLL, but they may be on - either side of the edited elements. Elements at the end with be - START-TRIMMED to the new end position of the edited element. Elements - at the start will be END-TRIMMED to the new start position of the - edited element. Acting on the start or end of the element - (#GES_EDGE_START and #GES_EDGE_END) is not defined. The element can - not shift layers under this mode. - - - Return a string representation of @mode. - - - a string representation of @mode. - - - - - a #GESEditMode - - - - - - - Currently we only support effects with N sinkpads and one single srcpad. -Apart from `gesaudiomixer` and `gescompositor` which can be used as effects -and where sinkpads will be requested as needed based on the timeline topology -GES will always request at most one sinkpad per effect (when required). - -> Note: GES always adds converters (`audioconvert ! audioresample ! -> audioconvert` for audio effects and `videoconvert` for video effects) to -> make it simpler for end users. - - - - - Creates a new #GESEffect from the description of the bin. It should be -possible to determine the type of the effect through the element -'klass' metadata of the GstElements that will be created. -In that corner case, you should use: -#ges_asset_request (GES_TYPE_EFFECT, "audio your ! bin ! description", NULL); -and extract that asset to be in full control. - - - a newly created #GESEffect, or %NULL if something went -wrong. - - - - - The gst-launch like bin description of the effect - - - - - - The description of the effect bin with a gst-launch-style -pipeline description. - -Example: "videobalance saturation=1.5 hue=+0.5" - - - - - - - - - - - - - - - - This asset has a GStreamer bin-description as ID and is able to determine -to what track type the effect should be used in. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - - - - - Register an element that can change the rate at which media is playing. -The property type must be float or double, and must be a factor of the -rate, i.e. a value of 2.0 must mean that the media plays twice as fast. -Several properties may be registered for a single element type, -provided they all contribute to the rate as independent factors. For -example, this is true for the "GstPitch::rate" and "GstPitch::tempo" -properties. These are already registered by default in GES, along with -#videorate:rate for #videorate and #scaletempo:rate for #scaletempo. - -If such a rate property becomes a child property of a #GESEffect upon -its creation (the element is part of its #GESEffect:bin-description), -it will be automatically registered as a time property (see -ges_base_effect_register_time_property()) and will have its time -translation functions set (see -ges_base_effect_set_time_translation_funcs()) to use the overall rate -of the rate properties. Note that if an effect contains a rate -property as well as a non-rate time property, you should ensure to set -the time translation functions to some other methods using -ges_base_effect_set_time_translation_funcs(). - -Note, you can obtain a reference to the GESEffectClass using - -``` - GES_EFFECT_CLASS (g_type_class_ref (GES_TYPE_EFFECT)); -``` - - - %TRUE if the rate property was successfully registered. When -this method returns %FALSE, a warning is emitted with more information. - - - - - Instance of the GESEffectClass - - - - The #GstElementFactory name of the element that changes -the rate - - - - The name of the property that changes the rate - - - - - - - The effect will be applied on the sources that have lower priorities -(higher number) between the inpoint and the end of it. - -The asset ID of an effect clip is in the form: - -``` - "audio ! bin ! description || video ! bin ! description" -``` - - - - - Creates a new #GESEffectClip from the description of the bin. - - - a newly created #GESEffectClip, or -%NULL if something went wrong. - - - - - The gst-launch like bin description of the effect - - - - The gst-launch like bin description of the effect - - - - - - The description of the audio track of the effect bin with a gst-launch-style -pipeline description. This should be used for test purposes. - -Example: "audiopanorama panorama=1.0" - - - - The description of the video track of the effect bin with a gst-launch-style -pipeline description. This should be used for test purposes. - -Example: "videobalance saturation=1.5 hue=+0.5" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The ID passed is malformed - - - An error happened while loading the asset - - - The formatted files was malformed - - - The frame number is invalid - - - The operation would lead to a negative -#GES_TIMELINE_ELEMENT_LAYER_PRIORITY. (Since: 1.18) - - - The operation would lead to a negative time. -E.g. for the #GESTimelineElement:start #GESTimelineElement:duration or -#GESTimelineElement:in-point. (Since: 1.18) - - - Some #GESTimelineElement does -not have a large enough #GESTimelineElement:max-duration to cover the -desired operation. (Since: 1.18) - - - The operation would break one of -the overlap conditions for the #GESTimeline. (Since: 1.18) - - - - - - A #GObject that implements the #GESExtractable interface can be -extracted from a #GESAsset using ges_asset_extract(). - -Each extractable type will have its own way of interpreting the -#GESAsset:id of an asset (or, if it is associated with a specific -subclass of #GESAsset, the asset subclass may handle the -interpretation of the #GESAsset:id). By default, the requested asset -#GESAsset:id will be ignored by a #GESExtractable and will be set to -the type name of the extractable instead. Also by default, when the -requested asset is extracted, the returned object will simply be a -newly created default object of that extractable type. You should check -the documentation for each extractable type to see if they differ from -the default. - -After the object is extracted, it will have a reference to the asset it -came from, which you can retrieve using ges_extractable_get_asset(). - - - - Gets the #GESAsset:id of some associated asset. It may be the case -that the object has no set asset, or even that such an asset does not -yet exist in the GES cache. Instead, this will return the asset -#GESAsset:id that is _compatible_ with the current state of the object, -as determined by the #GESExtractable implementer. If it was indeed -extracted from an asset, this should return the same as its -corresponding asset #GESAsset:id. - - - The #GESAsset:id of some associated #GESAsset -that is compatible with @self's current state. - - - - - A #GESExtractable - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the asset that has been set on the extractable object. - - - The asset set on @self, or %NULL -if no asset has been set. - - - - - A #GESExtractable - - - - - - Gets the #GESAsset:id of some associated asset. It may be the case -that the object has no set asset, or even that such an asset does not -yet exist in the GES cache. Instead, this will return the asset -#GESAsset:id that is _compatible_ with the current state of the object, -as determined by the #GESExtractable implementer. If it was indeed -extracted from an asset, this should return the same as its -corresponding asset #GESAsset:id. - - - The #GESAsset:id of some associated #GESAsset -that is compatible with @self's current state. - - - - - A #GESExtractable - - - - - - Sets the asset for this extractable object. - -When an object is extracted from an asset using ges_asset_extract() its -asset will be automatically set. Note that many classes that implement -#GESExtractable will automatically create their objects using assets -when you call their @new methods. However, you can use this method to -associate an object with a compatible asset if it was created by other -means and does not yet have an asset. Or, for some implementations of -#GESExtractable, you can use this to change the asset of the given -extractable object, which will lead to a change in its state to -match the new asset #GESAsset:id. - - - %TRUE if @asset could be successfully set on @self. - - - - - A #GESExtractable - - - - The asset to set - - - - - - - Method for checking that an ID is valid for the given #GESExtractable -type. If the given ID is considered valid, it can be adjusted into some -standard and returned to prevent the creation of separate #GESAsset-s, -with different #GESAsset:id, that would otherwise act the same. - -Returns (transfer full) (nullable): The actual #GESAsset:id to set on -any corresponding assets, based on @id, or %NULL if @id is not valid. - - - - - - - The #GESExtractable type to check @id for - - - - The ID to check - - - - - - - - - - - The subclass type of #GESAsset that should be created when -an asset with the corresponding #GESAsset:extractable-type is -requested. - - - - The method to call to check whether a given ID is valid as -an asset #GESAsset:id for the given #GESAsset:extractable-type. The -returned ID is the actual #GESAsset:id that is set on the asset. The -default implementation will simply always return the type name of the -#GESAsset:extractable-type, even if the received ID is %NULL. As such, -any given ID is considered valid (or is ignored), but only one is -actually ever set on an asset, which means the given -#GESAsset:extractable-type can only have one associated asset. - - - - Whether an object of this class can have its -#GESAsset change over its lifetime. This should be set to %TRUE if one -of the object's parameters that is associated with its ID can change -after construction, which would require an asset with a new ID. Note -that the subclass is required to handle the requesting and setting of -the new asset on the object. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GESAsset:id of some associated #GESAsset -that is compatible with @self's current state. - - - - - A #GESExtractable - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Tests if a given GESFrameNumber represents a valid frame - - - - - - - - Constant to define an undefined frame number - - - - - A function that will be called when the nleobject of a corresponding -track element needs to be filled. - -The implementer of this function shall add the proper #GstElement to @nleobj -using gst_bin_add(). - This method type is no longer used. - - - %TRUE if the implementer successfully filled the @nleobj. - - - - - The #GESClip controlling the track elements - - - - The #GESTrackElement - - - - The nleobject that needs to be filled - - - - - - Base class for timeline data serialization and deserialization. - - - - Checks if there is a #GESFormatter available which can load a #GESTimeline -from the given URI. - - - TRUE if there is a #GESFormatter that can support the given uri -or FALSE if not. - - - - - a #gchar * pointing to the URI - - - - - - Returns TRUE if there is a #GESFormatter available which can save a -#GESTimeline to the given URI. - - - TRUE if the given @uri is supported, else FALSE. - - - - - a #gchar * pointing to a URI - - - - - - Get the default #GESAsset to use as formatter. It will return -the asset for the #GESFormatter that has the highest @rank - - - The #GESAsset for the formatter with highest @rank - - - - - - - - - - - - - - - - - - - Load data from the given URI into timeline. - Use @ges_timeline_load_from_uri - - - TRUE if the timeline data was successfully loaded from the URI, -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - - - Save data from timeline to the given URI. - Use @ges_timeline_save_to_uri - - - TRUE if the timeline data was successfully saved to the URI -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - %TRUE to overwrite file if it exists - - - - - - Load data from the given URI into timeline. - Use @ges_timeline_load_from_uri - - - TRUE if the timeline data was successfully loaded from the URI, -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - - - Save data from timeline to the given URI. - Use @ges_timeline_save_to_uri - - - TRUE if the timeline data was successfully saved to the URI -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - %TRUE to overwrite file if it exists - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GES Formatter class. Override the vmethods to implement the formatter functionnality. - - - the parent class structure - - - - Whether the URI can be loaded - - - - class method to deserialize data from a URI - - - - class method to serialize data to a URI - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The class to register metas on - - - - The name of the formatter - - - - The formatter description - - - - A list of coma separated file extensions handled -by the formatter. The order of the extensions should match the -list of the structures inside @caps - - - - The caps the formatter handled, they should match what -gstreamer typefind mechanism will report for the files the formatter -handles. - - - - The version of the formatter - - - - The rank of the formatter - - - - - - - Virtual method for loading a timeline from a given URI. - -Every #GESFormatter subclass needs to implement this method. - - - TRUE if the timeline data was successfully loaded from the URI, -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - - - - - - Virtual method for saving a timeline to a uri. - -Every #GESFormatter subclass needs to implement this method. - - - TRUE if the timeline data was successfully saved to the URI -else FALSE. - - - - - a #GESFormatter - - - - a #GESTimeline - - - - a #gchar * pointing to a URI - - - - %TRUE to overwrite file if it exists - - - - - - A #GESGroup controls one or more #GESContainer-s (usually #GESClip-s, -but it can also control other #GESGroup-s). Its children must share -the same #GESTimeline, but can otherwise lie in separate #GESLayer-s -and have different timings. - -To initialise a group, you may want to use ges_container_group(), -and similarly use ges_container_ungroup() to dispose of it. - -A group will maintain the relative #GESTimelineElement:start times of -its children, as well as their relative layer #GESLayer:priority. -Therefore, if one of its children has its #GESTimelineElement:start -set, all other children will have their #GESTimelineElement:start -shifted by the same amount. Similarly, if one of its children moves to -a new layer, the other children will also change layers to maintain the -difference in their layer priorities. For example, if a child moves -from a layer with #GESLayer:priority 1 to a layer with priority 3, then -another child that was in a layer with priority 0 will move to the -layer with priority 2. - -The #GESGroup:start of a group refers to the earliest start -time of its children. If the group's #GESGroup:start is set, all the -children will be shifted equally such that the earliest start time -will match the set value. The #GESGroup:duration of a group is the -difference between the earliest start time and latest end time of its -children. If the group's #GESGroup:duration is increased, the children -whose end time matches the end of the group will be extended -accordingly. If it is decreased, then any child whose end time exceeds -the new end time will also have their duration decreased accordingly. - -A group may span several layers, but for methods such as -ges_timeline_element_get_layer_priority() and -ges_timeline_element_edit() a group is considered to have a layer -priority that is the highest #GESLayer:priority (numerically, the -smallest) of all the layers it spans. - - - - - Created a new empty group. You may wish to use -ges_container_group() instead, which can return a different -#GESContainer subclass if possible. - - - The new empty group. - - - - - An overwrite of the #GESTimelineElement:duration property. For a -#GESGroup, this is the difference between the earliest -#GESTimelineElement:start time and the latest end time (given by -#GESTimelineElement:start + #GESTimelineElement:duration) amongst -its children. - - - - An overwrite of the #GESTimelineElement:in-point property. This has -no meaning for a group and should not be set. - - - - An overwrite of the #GESTimelineElement:max-duration property. This -has no meaning for a group and should not be set. - - - - An overwrite of the #GESTimelineElement:priority property. -Setting #GESTimelineElement priorities is deprecated as all priority -management is now done by GES itself. - - - - An overwrite of the #GESTimelineElement:start property. For a -#GESGroup, this is the earliest #GESTimelineElement:start time -amongst its children. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Outputs the video stream from a given file as a still frame. The frame chosen -will be determined by the in-point property on the track element. For image -files, do not set the in-point property. - This won't be used anymore and has been replaced by -#GESUriSource instead which now plugs an `imagefreeze` element when -#ges_uri_source_asset_is_image returns %TRUE. - - - - - The location of the file/resource to use. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GESLayer-s are responsible for collecting and ordering #GESClip-s. - -A layer within a timeline will have an associated priority, -corresponding to their index within the timeline. A layer with the -index/priority 0 will have the highest priority and the layer with the -largest index will have the lowest priority (the order of priorities, -in this sense, is the _reverse_ of the numerical ordering of the -indices). ges_timeline_move_layer() should be used if you wish to -change how layers are prioritised in a timeline. - -Layers with higher priorities will have their content priorities -over content from lower priority layers, similar to how layers are -used in image editing. For example, if two separate layers both -display video content, then the layer with the higher priority will -have its images shown first. The other layer will only have its image -shown if the higher priority layer has no content at the given -playtime, or is transparent in some way. Audio content in separate -layers will simply play in addition. - - - - - Creates a new layer. - - - A new layer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - See ges_layer_add_asset_full(), which also gives an error. - - - The newly created clip. - - - - - The #GESLayer - - - - The asset to extract the new clip from - - - - The #GESTimelineElement:start value to set on the new clip -If `start == #GST_CLOCK_TIME_NONE`, it will be added to the end -of @layer, i.e. it will be set to @layer's duration - - - - The #GESTimelineElement:in-point value to set on the new -clip - - - - The #GESTimelineElement:duration value to set on the new -clip - - - - The #GESClip:supported-formats to set on the the new -clip, or #GES_TRACK_TYPE_UNKNOWN to use the default - - - - - - Extracts a new clip from an asset and adds it to the layer with -the given properties. - - - The newly created clip. - - - - - The #GESLayer - - - - The asset to extract the new clip from - - - - The #GESTimelineElement:start value to set on the new clip -If `start == #GST_CLOCK_TIME_NONE`, it will be added to the end -of @layer, i.e. it will be set to @layer's duration - - - - The #GESTimelineElement:in-point value to set on the new -clip - - - - The #GESTimelineElement:duration value to set on the new -clip - - - - The #GESClip:supported-formats to set on the the new -clip, or #GES_TRACK_TYPE_UNKNOWN to use the default - - - - - - See ges_layer_add_clip_full(), which also gives an error. - - - %TRUE if @clip was properly added to @layer, or %FALSE -if @layer refused to add @clip. - - - - - The #GESLayer - - - - The clip to add - - - - - - Adds the given clip to the layer. If the method succeeds, the layer -will take ownership of the clip. - -This method will fail and return %FALSE if @clip already resides in -some layer. It can also fail if the additional clip breaks some -compositional rules (see #GESTimelineElement). - - - %TRUE if @clip was properly added to @layer, or %FALSE -if @layer refused to add @clip. - - - - - The #GESLayer - - - - The clip to add - - - - - - Gets whether the layer is active for the given track. See -ges_layer_set_active_for_tracks(). - - - %TRUE if @layer is active for @track, or %FALSE otherwise. - - - - - The #GESLayer - - - - The #GESTrack to check if @layer is currently active for - - - - - - Gets the #GESLayer:auto-transition of the layer. - - - %TRUE if transitions are automatically added to @layer. - - - - - The #GESLayer - - - - - - Get the #GESClip-s contained in this layer. - - - A list of clips in -@layer. - - - - - - - The #GESLayer - - - - - - Gets the clips within the layer that appear between @start and @end. - - - A list of #GESClip-s -that intersect the interval `[start, end)` in @layer. - - - - - - - The #GESLayer - - - - Start of the interval - - - - End of the interval - - - - - - Retrieves the duration of the layer, which is the difference -between the start of the layer (always time 0) and the end (which will -be the end time of the final clip). - - - The duration of @layer. - - - - - The layer to get the duration from - - - - - - Get the priority of the layer. When inside a timeline, this is its -index in the timeline. See ges_timeline_move_layer(). - - - The priority of @layer within its timeline. - - - - - The #GESLayer - - - - - - Gets the timeline that the layer is a part of. - - - The timeline that @layer -is currently part of, or %NULL if it is not associated with any -timeline. - - - - - The #GESLayer - - - - - - Convenience method to check if the layer is empty (doesn't contain -any #GESClip), or not. - - - %TRUE if @layer is empty, %FALSE if it contains at least -one clip. - - - - - The #GESLayer to check - - - - - - Removes the given clip from the layer. - - - %TRUE if @clip was removed from @layer, or %FALSE if the -operation failed. - - - - - The #GESLayer - - - - The clip to remove - - - - - - Activate or deactivate track elements in @tracks (or in all tracks if @tracks -is %NULL). - -When a layer is deactivated for a track, all the #GESTrackElement-s in -the track that belong to a #GESClip in the layer will no longer be -active in the track, regardless of their individual -#GESTrackElement:active value. - -Note that by default a layer will be active for all of its -timeline's tracks. - - - %TRUE if the operation worked %FALSE otherwise. - - - - - The #GESLayer - - - - Whether elements in @tracks should be active or not - - - - The list of -tracks @layer should be (de-)active in, or %NULL to include all the tracks -in the @layer's timeline - - - - - - - - Sets #GESLayer:auto-transition for the layer. Use -ges_timeline_set_auto_transition() if you want all layers within a -#GESTimeline to have #GESLayer:auto-transition set to %TRUE. Use this -method if you want different values for different layers (and make sure -to keep #GESTimeline:auto-transition as %FALSE for the corresponding -timeline). - - - - - - - The #GESLayer - - - - Whether transitions should be automatically added to -the layer - - - - - - Sets the layer to the given priority. See #GESLayer:priority. - use #ges_timeline_move_layer instead. This deprecation means -that you will not need to handle layer priorities at all yourself, GES -will make sure there is never 'gaps' between layer priorities. - - - - - - - The #GESLayer - - - - The priority to set - - - - - - - - - - - - - - - - - - - - Whether to automatically create a #GESTransitionClip whenever two -#GESSource-s that both belong to a #GESClip in the layer overlap. -See #GESTimeline for what counts as an overlap. - -When a layer is added to a #GESTimeline, if this property is left as -%FALSE, but the timeline's #GESTimeline:auto-transition is %TRUE, it -will be set to %TRUE as well. - - - - The priority of the layer in the #GESTimeline. 0 is the highest -priority. Conceptually, a timeline is a stack of layers, -and the priority of the layer represents its position in the stack. Two -layers should not have the same priority within a given GESTimeline. - -Note that the timeline needs to be committed (with #ges_timeline_commit) -for the change to be taken into account. - use #ges_timeline_move_layer instead. This deprecation means -that you will not need to handle layer priorities at all yourself, GES -will make sure there is never 'gaps' between layer priorities. - - - - - - - the #GESTimeline where this layer is being used. - - - - - - - - - - - - - - - - - - Will be emitted whenever the layer is activated or deactivated -for some #GESTrack. See ges_layer_set_active_for_tracks(). - - - - - - Whether @layer has been made active or de-active in the @tracks - - - - A list of #GESTrack -which have been activated or deactivated - - - - - - - - Will be emitted after the clip is added to the layer. - - - - - - The clip that was added - - - - - - Will be emitted after the clip is removed from the layer. - - - - - - The clip that was removed - - - - - - - Subclasses can override the @get_objects if they can provide a more -efficient way of providing the list of contained #GESClip-s. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The description of the object, to be used in various contexts (string). - - - - - The file extension of files produced by a #GESFormatter (string). - - - - - The mimetype used for the file produced by a #GESFormatter (string). - - - - - The name of a formatter, used as the #GESAsset:id for #GESFormatter -assets (string). - - - - - The rank of a #GESFormatter (a #GstRank). - - - - - The version of a #GESFormatter (double). - - - - - The version of the format in which a project is serialized (string). - - - - - The ARGB color of a #GESMarker (an AARRGGBB hex as a uint). - - - - - The volume for a #GESTrack or a #GESLayer (float). - - - - - The default volume for a #GESTrack or a #GESLayer as a float. - - - - - - - - - A timed #GESMetaContainer object. - - - - Current position (in nanoseconds) of the #GESMarker - - - - - - - - - - - A #GESMarker can be colored by setting the #GES_META_MARKER_COLOR meta. - - - Creates a new #GESMarkerList. - - - A new #GESMarkerList - - - - - - - The newly-added marker, the list keeps ownership -of the marker - - - - - - - - The position of the new marker - - - - - - - - a #GList -of the #GESMarker within the GESMarkerList. The user will have -to unref each #GESMarker and free the #GList. - - - - - - - - - - - - Moves a @marker in a @list to a new @position - - - %TRUE if the marker could be moved, %FALSE otherwise - (if the marker was not present in the list for example) - - - - - - - - - - - - - - - - Removes @marker from @list, this decreases the refcount of the -marker by 1. - - - %TRUE if the marker could be removed, %FALSE otherwise - (if the marker was not present in the list for example) - - - - - - - - - - - - - - - The number of markers in @list - - - - - - - - - - Will be emitted after the marker was added to the marker-list. - - - - - - the position of the added marker - - - - the #GESMarker that was added. - - - - - - Will be emitted after the marker was moved to. - - - - - - the previous position of the marker - - - - the new position of the marker - - - - the #GESMarker that was moved. - - - - - - Will be emitted after the marker was removed the marker-list. - - - - - - the #GESMarker that was removed. - - - - - - - - - - - - - A #GObject that implements #GESMetaContainer can have metadata set on -it, that is data that is unimportant to its function within GES, but -may hold some useful information. In particular, -ges_meta_container_set_meta() can be used to store any #GValue under -any generic field (specified by a string key). The same method can also -be used to remove the field by passing %NULL. A number of convenience -methods are also provided to make it easier to set common value types. -The metadata can then be read with ges_meta_container_get_meta() and -similar convenience methods. - -## Registered Fields - -By default, any #GValue can be set for a metadata field. However, you -can register some fields as static, that is they only allow values of a -specific type to be set under them, using -ges_meta_container_register_meta() or -ges_meta_container_register_static_meta(). The set #GESMetaFlag will -determine whether the value can be changed, but even if it can be -changed, it must be changed to a value of the same type. - -Internally, some GES objects will be initialized with static metadata -fields. These will correspond to some standard keys, such as -#GES_META_VOLUME. - - - Deserializes the given string, and adds and sets the found fields and -their values on the container. The string should be the return of -ges_meta_container_metas_to_string(). - - - %TRUE if the fields in @str was successfully deserialized -and added to @container. - - - - - A #GESMetaContainer - - - - A string to deserialize and add to @container - - - - - - Checks whether the specified field has been registered as static, and -gets the registered type and flags of the field, as used in -ges_meta_container_register_meta() and -ges_meta_container_register_static_meta(). - - - %TRUE if the @meta_item field has been registered on -@container. - - - - - A #GESMetaContainer - - - - The key for the @container field to check - - - - A destination to get the registered flags of -the field, or %NULL to ignore - - - - A destination to get the registered type of -the field, or %NULL to ignore - - - - - - Calls the given function on each of the meta container's set metadata -fields. - - - - - - - A #GESMetaContainer - - - - A function to call on each of @container's set -metadata fields - - - - User data to send to @func - - - - - - Gets the current boolean value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the boolean value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current date value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the date value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current date time value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the date time value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current double value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the double value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current float value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the float value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current int value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the int value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current int64 value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the int64 value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current marker list value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - A copy of the marker list value under @key, -or %NULL if it could not be fetched. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - - - Gets the current value of the specified field of the meta container. - - - The value under @key, or %NULL if @container -does not have the field set. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - - - Gets the current string value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - The string value under @meta_item, or %NULL -if it could not be fetched. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - - - Gets the current uint value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the uint value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Gets the current uint64 value of the specified field of the meta -container. If the field does not have a set value, or it is of the -wrong type, the method will fail. - - - %TRUE if the uint64 value under @meta_item was copied -to @dest. - - - - - A #GESMetaContainer - - - - The key for the @container field to get - - - - Destination into which the value under @meta_item -should be copied. - - - - - - Serializes the set metadata fields of the meta container to a string. - - - A serialized @container, or %NULL if an error -occurred. - - - - - A #GESMetaContainer - - - - - - Sets the value of the specified field of the meta container to the -given value, and registers the field to only hold a value of the -same type. After calling this, only values of the same type as @value -can be set for this field. The given flags can be set to make this -field only readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold @value types, with the given @flags, and the -field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given boolean value, and registers the field to only hold a boolean -typed value. After calling this, only boolean values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold boolean typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given date value, and registers the field to only hold a date -typed value. After calling this, only date values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold date typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given date time value, and registers the field to only hold a date time -typed value. After calling this, only date time values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold date time typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given double value, and registers the field to only hold a double -typed value. After calling this, only double values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold double typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given float value, and registers the field to only hold a float -typed value. After calling this, only float values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold float typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given int value, and registers the field to only hold an int -typed value. After calling this, only int values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold int typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given int64 value, and registers the field to only hold an int64 -typed value. After calling this, only int64 values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold int64 typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given string value, and registers the field to only hold a string -typed value. After calling this, only string values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold string typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given uint value, and registers the field to only hold a uint -typed value. After calling this, only uint values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold uint typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given uint64 value, and registers the field to only hold a uint64 -typed value. After calling this, only uint64 values can be set for -this field. The given flags can be set to make this field only -readable after calling this method. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold uint64 typed values, with the given @flags, -and the field was successfully set to @value. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The value to set for the registered field - - - - - - Registers a static metadata field on the container to only hold the -specified type. After calling this, setting a value under this field -can only succeed if its type matches the registered type of the field. - -Unlike ges_meta_container_register_meta(), no (initial) value is set -for this field, which means you can use this method to reserve the -space to be _optionally_ set later. - -Note that if a value has already been set for the field being -registered, then its type must match the registering type, and its -value will be left in place. If the field has no set value, then -you will likely want to include #GES_META_WRITABLE in @flags to allow -the value to be set later. - - - %TRUE if the @meta_item field was successfully registered on -@container to only hold @type values, with the given @flags. - - - - - A #GESMetaContainer - - - - Flags to be used for the registered field - - - - The key for the @container field to register - - - - The required value type for the registered field - - - - - - Sets the value of the specified field of the meta container to the -given boolean value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given date value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given date time value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given double value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given float value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given int value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given int64 value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given marker list value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to a -copy of the given value. If the given @value is %NULL, the field -given by @meta_item is removed and %TRUE is returned. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item, or %NULL to -remove the corresponding field - - - - - - Sets the value of the specified field of the meta container to the -given string value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given uint value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - Sets the value of the specified field of the meta container to the -given uint64 value. - - - %TRUE if @value was set under @meta_item for @container. - - - - - A #GESMetaContainer - - - - The key for the @container field to set - - - - The value to set under @meta_item - - - - - - This is emitted for a meta container whenever the metadata under one -of its fields changes, is set for the first time, or is removed. In -the latter case, @value will be %NULL. - - - - - - The key for the @container field that changed - - - - The new value under @key - - - - - - - - - - - - - - - - - - - The metadata is readable - - - The metadata is writable - - - The metadata is readable and writable - - - - A method to be called on all of a meta container's fields. - - - - - - - A #GESMetaContainer - - - - The key for one of @container's fields - - - - The set value under @key - - - - User data - - - - - - Outputs the video stream from a given image sequence. The start frame chosen -will be determined by the in-point property on the track element. - -This should not be used anymore, the `imagesequence://` protocol should be -used instead. Check the #imagesequencesrc GStreamer element for more -information. - Use #GESUriSource instead - - - - - - - - - - - - - - - - The uri of the file/resource to use. You can set a start index, -a stop index and a sequence pattern. -The format is &lt;multifile://start:stop\@location-pattern&gt;. -The pattern uses printf string formating. - -Example uris: - -multifile:///home/you/image\%03d.jpg - -multifile://20:50@/home/you/sequence/\%04d.png - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for overlays, transitions, and effects - - - - - - - - - - - - - - - - - - - - - - - - - - - - Operations are any kind of object that both outputs AND consumes data. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Overlays are objects which modify the underlying layer(s). - -Examples of overlays include text, image watermarks, or audio dubbing. - -Transitions, which change from one source to another over time, are -not considered overlays. - - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - - - - - - - - - - - - - - A #GESPipeline can take an audio-video #GESTimeline and conveniently -link its #GESTrack-s to an internal #playsink element, for -preview/playback, and an internal #encodebin element, for rendering. -You can switch between these modes using ges_pipeline_set_mode(). - -You can choose the specific audio and video sinks used for previewing -the timeline by setting the #GESPipeline:audio-sink and -#GESPipeline:video-sink properties. - -You can set the encoding and save location used in rendering by calling -ges_pipeline_set_render_settings(). - - - - - Creates a new pipeline. - - - The newly created pipeline. - - - - - Gets the #GESPipeline:mode of the pipeline. - - - The current mode of @pipeline. - - - - - A #GESPipeline - - - - - - Gets a sample from the pipeline of the currently displayed image in -preview, in the specified format. - -Note that if you use "ANY" caps for @caps, then the current format of -the image is used. You can retrieve these caps from the returned sample -with gst_sample_get_caps(). - - - A sample of @self's current image preview in -the format given by @caps, or %NULL if an error prevented fetching the -sample. - - - - - A #GESPipeline in #GST_STATE_PLAYING or #GST_STATE_PAUSED - - - - Some caps to specifying the desired format, or -#GST_CAPS_ANY to use the native format - - - - - - Gets a sample from the pipeline of the currently displayed image in -preview, in the 24-bit "RGB" format and of the desired width and -height. - -See ges_pipeline_get_thumbnail(). - - - A sample of @self's current image preview in -the "RGB" format, scaled to @width and @height, or %NULL if an error -prevented fetching the sample. - - - - - A #GESPipeline in %GST_STATE_PLAYING or %GST_STATE_PAUSED - - - - The requested pixel width of the image, or -1 to use the native -size - - - - The requested pixel height of the image, or -1 to use the -native size - - - - - - Gets the #GESPipeline:audio-sink of the pipeline. - - - The audio sink used by @self for preview. - - - - - A #GESPipeline - - - - - - Gets the #GESPipeline:video-sink of the pipeline. - - - The video sink used by @self for preview. - - - - - A #GESPipeline - - - - - - Sets the #GESPipeline:audio-sink of the pipeline. - - - - - - - A #GESPipeline in #GST_STATE_NULL - - - - A audio sink for @self to use for preview - - - - - - Sets the #GESPipeline:video-sink of the pipeline. - - - - - - - A #GESPipeline in #GST_STATE_NULL - - - - A video sink for @self to use for preview - - - - - - Saves the currently displayed image of the pipeline in preview to the -given location, in the specified dimensions and format. - - - %TRUE if @self's current image preview was successfully saved -to @location using the given @format, @height and @width. - - - - - A #GESPipeline in %GST_STATE_PLAYING or %GST_STATE_PAUSED - - - - The requested pixel width of the image, or -1 to use the native -size - - - - The requested pixel height of the image, or -1 to use the -native size - - - - The desired mime type (for example, "image/jpeg") - - - - The path to save the thumbnail to - - - - - - Sets the #GESPipeline:mode of the pipeline. - -Note that the pipeline will be set to #GST_STATE_NULL during this call to -perform the necessary changes. You will need to set the state again yourself -after calling this. - -> **NOTE**: [Rendering settings](ges_pipeline_set_render_settings) need to be -> set before setting @mode to #GES_PIPELINE_MODE_RENDER or -> #GES_PIPELINE_MODE_SMART_RENDER, the call to this method will fail -> otherwise. - - - %TRUE if the mode of @pipeline was successfully set to @mode. - - - - - A #GESPipeline - - - - The mode to set for @pipeline - - - - - - Specifies encoding setting to be used by the pipeline to render its -#GESPipeline:timeline, and where the result should be written to. - -This method **must** be called before setting the pipeline mode to -#GES_PIPELINE_MODE_RENDER. - - - %TRUE if the settings were successfully set on @pipeline. - - - - - A #GESPipeline - - - - The URI to save the #GESPipeline:timeline rendering -result to - - - - The encoding to use for rendering the #GESPipeline:timeline - - - - - - Takes the given timeline and sets it as the #GESPipeline:timeline for -the pipeline. - -Note that you should only call this method once on a given pipeline -because a pipeline can not have its #GESPipeline:timeline changed after -it has been set. - - - %TRUE if @timeline was successfully given to @pipeline. - - - - - A #GESPipeline - - - - The timeline to set for @pipeline - - - - - - The audio filter(s) to apply during playback in preview mode, -immediately before the #GESPipeline:audio-sink. This exposes the -#playsink:audio-filter property of the internal #playsink. - - - - The audio sink used for preview. This exposes the -#playsink:audio-sink property of the internal #playsink. - - - - The pipeline's mode. In preview mode (for audio or video, or both) -the pipeline can display the timeline's content to an end user. In -rendering mode the pipeline can encode the timeline's content and -save it to a file. - - - - The timeline used by this pipeline, whose content it will play and -render, or %NULL if the pipeline does not yet have a timeline. - -Note that after you set the timeline for the first time, subsequent -calls to change the timeline will fail. - - - - The video filter(s) to apply during playback in preview mode, -immediately before the #GESPipeline:video-sink. This exposes the -#playsink:video-filter property of the internal #playsink. - - - - The video sink used for preview. This exposes the -#playsink:video-sink property of the internal #playsink. - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - The various modes a #GESPipeline can be configured to. - - Output the #GESPipeline:timeline's -audio to the soundcard - - - Output the #GESPipeline:timeline's -video to the screen - - - Output both the #GESPipeline:timeline's -audio and video to the soundcard and screen (default) - - - Render the #GESPipeline:timeline with -forced decoding (the underlying #encodebin has its -#encodebin:avoid-reencoding property set to %FALSE) - - - Render the #GESPipeline:timeline, -avoiding decoding/reencoding (the underlying #encodebin has its -#encodebin:avoid-reencoding property set to %TRUE). -> NOTE: Smart rendering can not work in tracks where #GESTrack:mixing -> is enabled. - - - - - - - - This is a legacy format and you should avoid to use it. The formatter -is really not in good shape and is deprecated. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GESProject is used to control a set of #GESAsset and is a -#GESAsset with `GES_TYPE_TIMELINE` as @extractable_type itself. That -means that you can extract #GESTimeline from a project as followed: - -|[ - GESProject *project; - GESTimeline *timeline; - - project = ges_project_new ("file:///path/to/a/valid/project/uri"); - - // Here you can connect to the various signal to get more infos about - // what is happening and recover from errors if possible - ... - - timeline = ges_asset_extract (GES_ASSET (project)); -]| - -The #GESProject class offers a higher level API to handle #GESAsset-s. -It lets you request new asset, and it informs you about new assets through -a set of signals. Also it handles problem such as missing files/missing -#GstElement and lets you try to recover from those. - -## Subprojects - -In order to add a subproject, the only thing to do is to add the subproject -to the main project: - -``` c -ges_project_add_asset (project, GES_ASSET (subproject)); -``` -then the subproject will be serialized in the project files. To use -the subproject in a timeline, you should use a #GESUriClip with the -same subproject URI. - -When loading a project with subproject, subprojects URIs will be temporary -writable local files. If you want to edit the subproject timeline, -you should retrieve the subproject from the parent project asset list and -extract the timeline with ges_asset_extract() and save it at -the same temporary location. - - - - - - Creates a new #GESProject and sets its uri to @uri if provided. Note that -if @uri is not valid or %NULL, the uri of the project will then be set -the first time you save the project. If you then save the project to -other locations, it will never be updated again and the first valid URI is -the URI it will keep refering to. - - - A newly created #GESProject - - - - - The uri to be set after creating the project. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The self - - - - The loading timeline - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Adds a #GESAsset to @project, the project will keep a reference on -@asset. - - - %TRUE if the asset could be added %FALSE it was already -in the project - - - - - A #GESProject - - - - A #GESAsset to add to @project - - - - - - Adds @profile to the project. It lets you save in what format -the project has been renders and keep a reference to those formats. -Also, those formats will be saves to the project file when possible. - - - %TRUE if @profile could be added, %FALSE otherwize - - - - - A #GESProject - - - - A #GstEncodingProfile to add to the project. If a profile with -the same name already exists, it will be replaced - - - - - - Adds a formatter as used to load @project - - - - - - - The project to add a formatter to - - - - A formatter used by @project - - - - - - Create and add a #GESAsset to @project. You should connect to the -"asset-added" signal to get the asset when it finally gets added to -@project - - - %TRUE if the asset started to be added %FALSE it was already -in the project - - - - - A #GESProject - - - - The id of the asset to create and add to @project - - - - The #GType of the asset to create - - - - - - Create and add a #GESAsset to @project. You should connect to the -"asset-added" signal to get the asset when it finally gets added to -@project - - - The newly created #GESAsset or %NULL. - - - - - A #GESProject - - - - The id of the asset to create and add to @project - - - - The #GType of the asset to create - - - - - - - - The #GESAsset with -@id or %NULL if no asset with @id as an ID - - - - - A #GESProject - - - - The id of the asset to retrieve - - - - The extractable_type of the asset -to retrieve from @object - - - - - - Get the assets that are being loaded - - - A set of loading asset -that will be added to @project. Note that those Asset are *not* loaded yet, -and thus can not be used - - - - - - - A #GESProject - - - - - - Retrieve the uri that is currently set on @project - - - a newly allocated string representing uri. - - - - - A #GESProject - - - - - - List all @asset contained in @project filtering per extractable_type -as defined by @filter. It copies the asset and thus will not be updated -in time. - - - The list of -#GESAsset the object contains - - - - - - - A #GESProject - - - - Type of assets to list, `GES_TYPE_EXTRACTABLE` will list -all assets - - - - - - Lists the encoding profile that have been set to @project. The first one -is the latest added. - - - The -list of #GstEncodingProfile used in @project - - - - - - - A #GESProject - - - - - - Loads @project into @timeline - - - %TRUE if the project could be loaded %FALSE otherwize. - - - - - A #GESProject that has an @uri set already - - - - A blank timeline to load @project into - - - - - - remove a @asset to from @project. - - - %TRUE if the asset could be removed %FALSE otherwise - - - - - A #GESProject - - - - A #GESAsset to remove from @project - - - - - - Save the timeline of @project to @uri. You should make sure that @timeline -is one of the timelines that have been extracted from @project -(using ges_asset_extract (@project);) - - - %TRUE if the project could be save, %FALSE otherwize - - - - - A #GESProject to save - - - - The #GESTimeline to save, it must have been extracted from @project - - - - The uri where to save @project and @timeline - - - - The formatter asset to -use or %NULL. If %NULL, will try to save in the same format as the one -from which the timeline as been loaded or default to the best formatter -as defined in #ges_find_formatter_for_uri - - - - %TRUE to overwrite file if it exists - - - - - - - - - - - - - - - - - - - - - - - - - The #GESAsset that has been added to @project - - - - - - - - - - - The #GESAsset that started loading - - - - - - - - - - - The #GESAsset that has been removed from @project - - - - - - - - - - - The timeline that failed loading - - - - The #GError defining the error that occured - - - - - - Informs you that a #GESAsset could not be created. In case of -missing GStreamer plugins, the error will be set to #GST_CORE_ERROR -#GST_CORE_ERROR_MISSING_PLUGIN - - - - - - The #GError defining the error that occured, might be %NULL - - - - The @id of the asset that failed loading - - - - The @extractable_type of the asset that -failed loading - - - - - - - - - - - The #GESTimeline that completed loading - - - - - - - - - - - The #GESTimeline that started loading - - - - - - |[ -static gchar -source_moved_cb (GESProject *project, GError *error, GESAsset *asset_with_error) -{ - return g_strdup ("file:///the/new/uri.ogg"); -} - -static int -main (int argc, gchar ** argv) -{ - GESTimeline *timeline; - GESProject *project = ges_project_new ("file:///some/uri.xges"); - - g_signal_connect (project, "missing-uri", source_moved_cb, NULL); - timeline = ges_asset_extract (GES_ASSET (project)); -} -]| - - The new URI of @wrong_asset - - - - - The error that happened - - - - The asset with the wrong ID, you should us it and its content -only to find out what the new location is. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The self - - - - The loading timeline - - - - - - - - - - - - - - - - Base class for single-media sources - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GESSourceClip-s are clips whose core elements are #GESSource-s. - -## Effects - -#GESSourceClip-s can also have #GESBaseEffect-s added as non-core -elements. These effects are applied to the core sources of the clip -that they share a #GESTrack with. See #GESClip for how to add and move -these effects from the clip. - - - - - Creates a new #GESSourceClip that renders a time overlay on top - - - The newly created #GESSourceClip, -or %NULL if there was an error. - - - - - - - - - - - - - - - - - An asset types from which #GESSourceClip will be extracted - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GESTimelineElement:duration of @obj. - - - - A #GESTimelineElement - - - - - The end position of @obj: #GESTimelineElement:start + -#GESTimelineElement:duration. - - - - A #GESTimelineElement - - - - - The #GESTimelineElement:in-point of @obj. - - - - A #GESTimelineElement - - - - - See #ges_timeline_element_get_layer_priority. - - - - The object to retrieve the layer priority from - - - - - The #GESTimelineElement:max-duration of @obj. - - - - A #GESTimelineElement - - - - - The #GESTimelineElement:name of @obj. - - - - A #GESTimelineElement - - - - - Layer priority when a timeline element is not in any layer. - - - - - The #GESTimelineElement:parent of @obj. - - - - A #GESTimelineElement - - - - - The #GESTimelineElement:priority of @obj. - - - - A #GESTimelineElement - - - - - The #GESTimelineElement:start of @obj. - - - - A #GESTimelineElement - - - - - The #GESTimelineElement:timeline of @obj. - - - - A #GESTimelineElement - - - - - - - - - - - - - - - - - - - What the default #GESTrackElement:has-internal-source value should be -for new elements from this class. - - - - A #GESTrackElementClass - - - - - Useful for testing purposes. - -## Asset - -The default asset ID is GESTestClip, but the framerate and video -size can be overridden using an ID of the form: - -``` -framerate=60/1, width=1920, height=1080, max-duration=5.0 -``` -Note: `max-duration` can be provided in seconds as float, or as GstClockTime -as guint64 or gint. - - - - - Creates a new #GESTestClip. - - - The newly created #GESTestClip, -or %NULL if there was an error. - - - - - Creates a new #GESTestClip for the provided @nick. - - - The newly created #GESTestClip, -or %NULL if there was an error. - - - - - the nickname for which to create the #GESTestClip - - - - - - Get the frequency @self generates. - - - The frequency @self generates. See audiotestsrc element. - - - - - a #GESTestClip - - - - - - Get the volume of the test audio signal applied on @self. - - - The volume of the test audio signal applied on @self. - - - - - a #GESTestClip - - - - - - Get the #GESVideoTestPattern which is applied on @self. - - - The #GESVideoTestPattern which is applied on @self. - - - - - a #GESTestClip - - - - - - Let you know if the audio track of @self is muted or not. - - - Whether the audio track of @self is muted or not. - - - - - a #GESTestClip - - - - - - Sets the frequency to generate. See audiotestsrc element. - - - - - - - the #GESTestClip to set the frequency on - - - - the frequency you want to use on @self - - - - - - Sets whether the audio track of this clip is muted or not. - - - - - - - the #GESTestClip on which to mute or unmute the audio track - - - - %TRUE to mute the audio track, %FALSE to unmute it - - - - - - Sets the volume of the test audio signal. - - - - - - - the #GESTestClip to set the volume on - - - - the volume of the audio signal you want to use on @self - - - - - - Sets which video pattern to display on @self. - - - - - - - the #GESTestClip to set the pattern on - - - - the #GESVideoTestPattern to use on @self - - - - - - The frequency to generate for audio track elements. - - - - Whether the sound will be played or not. - - - - The volume for the audio track elements. - - - - Video pattern to display in video track elements. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Horizontal alignment of the text. - - align text left - - - align text center - - - align text right - - - align text on xpos position - - - - - - - - - - Creates a new #GESTextOverlay. - This should never be called by applications as this will -be created by clips. - - - The newly created #GESTextOverlay or -%NULL if something went wrong. - - - - - Get the color used by @source. - - - The color used by @source. - - - - - a GESTextOverlay - - - - - - Get the pango font description currently set on @source. - - - The pango font description currently set on @source. - - - - - a GESTextOverlay - - - - - - Get the horizontal aligment used by @source. - - - The horizontal aligment used by @source. - - - - - a GESTextOverlay - - - - - - Get the text currently set on @source. - - - The text currently set on @source. - - - - - a GESTextOverlay - - - - - - Get the vertical aligment used by @source. - - - The vertical aligment used by @source. - - - - - a GESTextOverlay - - - - - - Get the horizontal position used by @source. - - - The horizontal position used by @source. - - - - - a GESTextOverlay - - - - - - Get the vertical position used by @source. - - - The vertical position used by @source. - - - - - a GESTextOverlay - - - - - - Sets the color of the text. - - - - - - - the #GESTextOverlay* to set - - - - The color @self is being set to - - - - - - Sets the pango font description of the text this track element -will render. - - - - - - - the #GESTextOverlay - - - - the pango font description - - - - - - Sets the horizontal aligment of the text. - - - - - - - the #GESTextOverlay* to set text on - - - - The #GESTextHAlign defining the horizontal alignment -of the text render by @self. - - - - - - Sets the text this track element will render. - - - - - - - the #GESTextOverlay* to set text on - - - - the text to render. an internal copy of this text will be -made. - - - - - - Sets the vertical aligment of the text. - - - - - - - the #GESTextOverlay* to set text on - - - - The #GESTextVAlign defining the vertical alignment -of the text render by @self. - - - - - - Sets the horizontal position of the text. - - - - - - - the #GESTextOverlay* to set - - - - The horizontal position @self is being set to - - - - - - Sets the vertical position of the text. - - - - - - - the #GESTextOverlay* to set - - - - The vertical position @self is being set to - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Renders text onto the next lower priority stream using textrender. - - - - - Creates a new #GESTextOverlayClip - - - The newly created -#GESTextOverlayClip, or %NULL if there was an error. - - - - - Get the color used by @source. - - - The color used by @source. - - - - - a #GESTextOverlayClip - - - - - - Get the pango font description used by @self. - - - The pango font description used by @self. - - - - - a #GESTextOverlayClip - - - - - - Get the horizontal aligment used by @self. - - - The horizontal aligment used by @self. - - - - - a #GESTextOverlayClip - - - - - - Get the text currently set on @self. - - - The text currently set on @self. - - - - - a #GESTextOverlayClip - - - - - - Get the vertical aligment used by @self. - - - The vertical aligment used by @self. - - - - - a #GESTextOverlayClip - - - - - - Get the horizontal position used by @source. - - - The horizontal position used by @source. - - - - - a #GESTextOverlayClip - - - - - - Get the vertical position used by @source. - - - The vertical position used by @source. - - - - - a #GESTextOverlayClip - - - - - - Sets the color of the text. - - - - - - - the #GESTextOverlayClip* to set - - - - The color @self is being set to - - - - - - Sets the pango font description of the text - - - - - - - the #GESTextOverlayClip* - - - - the pango font description - - - - - - Sets the horizontal aligment of the text. - - - - - - - the #GESTextOverlayClip* to set horizontal alignement of text on - - - - #GESTextHAlign - - - - - - Sets the text this clip will render. - - - - - - - the #GESTextOverlayClip* to set text on - - - - the text to render. an internal copy of this text will be -made. - - - - - - Sets the vertical aligment of the text. - - - - - - - the #GESTextOverlayClip* to set vertical alignement of text on - - - - #GESTextVAlign - - - - - - Sets the horizontal position of the text. - - - - - - - the #GESTextOverlayClip* to set - - - - The horizontal position @self is being set to - - - - - - Sets the vertical position of the text. - - - - - - - the #GESTextOverlayClip* to set - - - - The vertical position @self is being set to - - - - - - The color of the text - - - - Pango font description string - - - - Horizontal alignment of the text - - - - The text to diplay - - - - Vertical alignent of the text - - - - The horizontal position of the text - - - - The vertical position of the text - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Vertical alignment of the text. - - draw text on the baseline - - - draw text on the bottom - - - draw text on top - - - draw text on ypos position - - - draw text on the center - - - - - - #GESTimeline is the central object for any multimedia timeline. - -A timeline is composed of a set of #GESTrack-s and a set of -#GESLayer-s, which are added to the timeline using -ges_timeline_add_track() and ges_timeline_append_layer(), respectively. - -The contained tracks define the supported types of the timeline -and provide the media output. Essentially, each track provides an -additional source #GstPad. - -Most usage of a timeline will likely only need a single #GESAudioTrack -and/or a single #GESVideoTrack. You can create such a timeline with -ges_timeline_new_audio_video(). After this, you are unlikely to need to -work with the tracks directly. - -A timeline's layers contain #GESClip-s, which in turn control the -creation of #GESTrackElement-s, which are added to the timeline's -tracks. See #GESTimeline::select-tracks-for-object if you wish to have -more control over which track a clip's elements are added to. - -The layers are ordered, with higher priority layers having their -content prioritised in the tracks. This ordering can be changed using -ges_timeline_move_layer(). - -## Editing - -See #GESTimelineElement for the various ways the elements of a timeline -can be edited. - -If you change the timing or ordering of a timeline's -#GESTimelineElement-s, then these changes will not actually be taken -into account in the output of the timeline's tracks until the -ges_timeline_commit() method is called. This allows you to move its -elements around, say, in response to an end user's mouse dragging, with -little expense before finalising their effect on the produced data. - -## Overlaps and Auto-Transitions - -There are certain restrictions placed on how #GESSource-s may overlap -in a #GESTrack that belongs to a timeline. These will be enforced by -GES, so the user will not need to keep track of them, but they should -be aware that certain edits will be refused as a result if the overlap -rules would be broken. - -Consider two #GESSource-s, `A` and `B`, with start times `startA` and -`startB`, and end times `endA` and `endB`, respectively. The start -time refers to their #GESTimelineElement:start, and the end time is -their #GESTimelineElement:start + #GESTimelineElement:duration. These -two sources *overlap* if: - -+ they share the same #GESTrackElement:track (non %NULL), which belongs - to the timeline; -+ they share the same #GES_TIMELINE_ELEMENT_LAYER_PRIORITY; and -+ `startA < endB` and `startB < endA `. - -Note that when `startA = endB` or `startB = endA` then the two sources -will *touch* at their edges, but are not considered overlapping. - -If, in addition, `startA < startB < endA`, then we can say that the -end of `A` overlaps the start of `B`. - -If, instead, `startA <= startB` and `endA >= endB`, then we can say -that `A` fully overlaps `B`. - -The overlap rules for a timeline are that: - -1. One source cannot fully overlap another source. -2. A source can only overlap the end of up to one other source at its - start. -3. A source can only overlap the start of up to one other source at its - end. - -The last two rules combined essentially mean that at any given timeline -position, only up to two #GESSource-s may overlap at that position. So -triple or more overlaps are not allowed. - -If you switch on #GESTimeline:auto-transition, then at any moment when -the end of one source (the first source) overlaps the start of another -(the second source), a #GESTransitionClip will be automatically created -for the pair in the same layer and it will cover their overlap. If the -two elements are edited in a way such that the end of the first source -no longer overlaps the start of the second, the transition will be -automatically removed from the timeline. However, if the two sources -still overlap at the same edges after the edit, then the same -transition object will be kept, but with its timing and layer adjusted -accordingly. - -## Saving - -To save/load a timeline, you can use the ges_timeline_load_from_uri() -and ges_timeline_save_to_uri() methods that use the default format. - -## Playing - -A timeline is a #GstBin with a source #GstPad for each of its -tracks, which you can fetch with ges_timeline_get_pad_for_track(). You -will likely want to link these to some compatible sink #GstElement-s to -be able to play or capture the content of the timeline. - -You can use a #GESPipeline to easily preview/play the timeline's -content, or render it to a file. - - - - - - Creates a new empty timeline. - - - The new timeline. - - - - - Creates a new timeline containing a single #GESAudioTrack and a -single #GESVideoTrack. - - - The new timeline, or %NULL if the tracks -could not be created and added. - - - - - Creates a timeline from the given URI. - - - A new timeline if the uri was loaded -successfully, or %NULL if the uri could not be loaded. - - - - - The URI to load from - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Add a layer to the timeline. - -If the layer contains #GESClip-s, then this may trigger the creation of -their core track element children for the timeline's tracks, and the -placement of the clip's children in the tracks of the timeline using -#GESTimeline::select-tracks-for-object. Some errors may occur if this -would break one of the configuration rules of the timeline in one of -its tracks. In such cases, some track elements would fail to be added -to their tracks, but this method would still return %TRUE. As such, it -is advised that you only add clips to layers that already part of a -timeline. In such situations, ges_layer_add_clip() is able to fail if -adding the clip would cause such an error. - This method requires you to ensure the layer's -#GESLayer:priority will be unique to the timeline. Use -ges_timeline_append_layer() and ges_timeline_move_layer() instead. - - - %TRUE if @layer was properly added. - - - - - The #GESTimeline - - - - The layer to add - - - - - - Add a track to the timeline. - -If the timeline already contains clips, then this may trigger the -creation of their core track element children for the track, and the -placement of the clip's children in the track of the timeline using -#GESTimeline::select-tracks-for-object. Some errors may occur if this -would break one of the configuration rules for the timeline in the -track. In such cases, some track elements would fail to be added to the -track, but this method would still return %TRUE. As such, it is advised -that you avoid adding tracks to timelines that already contain clips. - - - %TRUE if @track was properly added. - - - - - The #GESTimeline - - - - The track to add - - - - - - Append a newly created layer to the timeline. The layer will -be added at the lowest #GESLayer:priority (numerically, the highest). - - - The newly created layer. - - - - - The #GESTimeline - - - - - - Commit all the pending changes of the clips contained in the -timeline. - -When changes happen in a timeline, they are not immediately executed -internally, in a way that effects the output data of the timeline. You -should call this method when you are done with a set of changes and you -want them to be executed. - -Any pending changes will be executed in the backend. The -#GESTimeline::commited signal will be emitted once this has completed. -You should not try to change the state of the timeline, seek it or add -tracks to it before receiving this signal. You can use -ges_timeline_commit_sync() if you do not want to perform other tasks in -the mean time. - -Note that all the pending changes will automatically be executed when -the timeline goes from #GST_STATE_READY to #GST_STATE_PAUSED, which is -usually triggered by a corresponding state changes in a containing -#GESPipeline. - - - %TRUE if pending changes were committed, or %FALSE if nothing -needed to be committed. - - - - - A #GESTimeline - - - - - - Commit all the pending changes of the clips contained in the -timeline and wait for the changes to complete. - -See ges_timeline_commit(). - - - %TRUE if pending changes were committed, or %FALSE if nothing -needed to be committed. - - - - - A #GESTimeline - - - - - - Gets #GESTimeline:auto-transition for the timeline. - - - The auto-transition of @self. - - - - - The #GESTimeline - - - - - - Get the current #GESTimeline:duration of the timeline - - - The current duration of @timeline. - - - - - The #GESTimeline - - - - - - Gets the element contained in the timeline with the given name. - - - The timeline element in @timeline -with the given @name, or %NULL if it was not found. - - - - - The #GESTimeline - - - - The name of the element to find - - - - - - This method allows you to convert a timeline #GstClockTime into its -corresponding #GESFrameNumber in the timeline's output. - - - The frame number @timestamp corresponds to. - - - - - A #GESTimeline - - - - The timestamp to get the corresponding frame number of - - - - - - This method allows you to convert a timeline output frame number into a -timeline #GstClockTime. For example, this time could be used to seek to a -particular frame in the timeline's output, or as the edit position for -an element within the timeline. - - - The timestamp corresponding to @frame_number in the output of @self. - - - - - The self on which to retrieve the timestamp for @frame_number - - - - The frame number to get the corresponding timestamp of in the - timeline coordinates - - - - - - Get the list of #GESGroup-s present in the timeline. - - - The list of -groups that contain clips present in @timeline's layers. -Must not be changed. - - - - - - - The #GESTimeline - - - - - - Retrieve the layer whose index in the timeline matches the given -priority. - - - The layer with the given -@priority, or %NULL if none was found. - -Since 1.6 - - - - - The #GESTimeline to retrieve a layer from - - - - The priority/index of the layer to find - - - - - - Get the list of #GESLayer-s present in the timeline. - - - The list of -layers present in @timeline sorted by priority. - - - - - - - The #GESTimeline - - - - - - Search for the #GstPad corresponding to the given timeline's track. -You can link to this pad to receive the output data of the given track. - - - The pad corresponding to @track, -or %NULL if there is an error. - - - - - The #GESTimeline - - - - A track - - - - - - Gets the #GESTimeline:snapping-distance for the timeline. - - - The snapping distance (in nanoseconds) of @timeline. - - - - - The #GESTimeline - - - - - - Search for the #GESTrack corresponding to the given timeline's pad. - - - The track corresponding to @pad, -or %NULL if there is an error. - - - - - The #GESTimeline - - - - A pad - - - - - - Get the list of #GESTrack-s used by the timeline. - - - The list of tracks -used by @timeline. - - - - - - - The #GESTimeline - - - - - - Check whether the timeline is empty or not. - - - %TRUE if @timeline is empty. - - - - - The #GESTimeline - - - - - - Loads the contents of URI into the timeline. - - - %TRUE if the timeline was loaded successfully from @uri. - - - - - An empty #GESTimeline into which to load the formatter - - - - The URI to load from - - - - - - Moves a layer within the timeline to the index given by -@new_layer_priority. -An index of 0 corresponds to the layer with the highest priority in a -timeline. If @new_layer_priority is greater than the number of layers -present in the timeline, it will become the lowest priority layer. - - - - - - - A #GESTimeline - - - - A layer within @timeline, whose priority should be changed - - - - The new index for @layer - - - - - - Paste an element inside the timeline. @element **must** be the return of -ges_timeline_element_copy() with `deep=TRUE`, -and it should not be changed before pasting. @element itself is not -placed in the timeline, instead a new element is created, alike to the -originally copied element. Note that the originally copied element must -also lie within @timeline, at both the point of copying and pasting. - -Pasting may fail if it would place the timeline in an unsupported -configuration. - -After calling this function @element should not be used. In particular, -@element can **not** be pasted again. Instead, you can copy the -returned element and paste that copy (although, this is only possible -if the paste was successful). - -See also ges_timeline_element_paste(). - - - The newly created element, or -%NULL if pasting fails. - - - - - The #GESTimeline onto which @element should be pasted - - - - The element to paste - - - - The position in the timeline @element should be pasted to, -i.e. the #GESTimelineElement:start value for the pasted element. - - - - The layer into which the element should be pasted. --1 means paste to the same layer from which @element has been copied from - - - - - - Removes a layer from the timeline. - - - %TRUE if @layer was properly removed. - - - - - The #GESTimeline - - - - The layer to remove - - - - - - Remove a track from the timeline. - - - %TRUE if @track was properly removed. - - - - - The #GESTimeline - - - - The track to remove - - - - - - Saves the timeline to the given location. If @formatter_asset is %NULL, -the method will attempt to save in the same format the timeline was -loaded from, before defaulting to the formatter with highest rank. - - - %TRUE if @timeline was successfully saved to @uri. - - - - - The #GESTimeline - - - - The location to save to - - - - The formatter asset to use, or %NULL - - - - %TRUE to overwrite file if it exists - - - - - - Sets #GESTimeline:auto-transition for the timeline. This will also set -the corresponding #GESLayer:auto-transition for all of the timeline's -layers to the same value. See ges_layer_set_auto_transition() if you -wish to set the layer's #GESLayer:auto-transition individually. - - - - - - - The #GESTimeline - - - - Whether transitions should be automatically added -to @timeline's layers - - - - - - Sets #GESTimeline:snapping-distance for the timeline. This new value -will only effect future snappings and will not be used to snap the -current element positions within the timeline. - - - - - - - The #GESTimeline - - - - The snapping distance to use (in nanoseconds) - - - - - - Whether to automatically create a transition whenever two -#GESSource-s overlap in a track of the timeline. See -#GESLayer:auto-transition if you want this to only happen in some -layers. - - - - The current duration (in nanoseconds) of the timeline. A timeline -'starts' at time 0, so this is the maximum end time of all of its -#GESTimelineElement-s. - - - - The distance (in nanoseconds) at which a #GESTimelineElement being -moved within the timeline should snap one of its #GESSource-s with -another #GESSource-s edge. See #GESEditMode for which edges can -snap during an edit. 0 means no snapping. - - - - - - - A list of #GESLayer-s sorted by -priority. NOTE: Do not modify. - - - - - - Deprecated:1.10: (element-type GES.Track): This is not thread -safe, use #ges_timeline_get_tracks instead. - - - - - - - - - - - - - - This signal will be emitted once the changes initiated by -ges_timeline_commit() have been executed in the backend. Use -ges_timeline_commit_sync() if you do not want to have to connect -to this signal. - - - - - - Will be emitted after the group is added to to the timeline. This can -happen when grouping with `ges_container_group`, or by adding -containers to a newly created group. - -Note that this should not be emitted whilst a timeline is being -loaded from its #GESProject asset. You should connect to the -project's #GESProject::loaded signal if you want to know which groups -were created for the timeline. - - - - - - The group that was added to @timeline - - - - - - Will be emitted after the group is removed from the timeline through -`ges_container_ungroup`. Note that @group will no longer contain its -former children, these are held in @children. - -Note that if a group is emptied, then it will no longer belong to the -timeline, but this signal will **not** be emitted in such a case. - - - - - - The group that was removed from @timeline - - - - A list -of #GESContainer-s that _were_ the children of the removed @group - - - - - - - - Will be emitted after the layer is added to the timeline. - -Note that this should not be emitted whilst a timeline is being -loaded from its #GESProject asset. You should connect to the -project's #GESProject::loaded signal if you want to know which -layers were created for the timeline. - - - - - - The layer that was added to @timeline - - - - - - Will be emitted after the layer is removed from the timeline. - - - - - - The layer that was removed from @timeline - - - - - - Simplified version of #GESTimeline::select-tracks-for-object which only -allows @track_element to be added to a single #GESTrack. - - A track to put @track_element into, or %NULL if -it should be discarded. - - - - - The clip that @track_element is being added to - - - - The element being added - - - - - - This will be emitted whenever the timeline needs to determine which -tracks a clip's children should be added to. The track element will -be added to each of the tracks given in the return. If a track -element is selected to go into multiple tracks, it will be copied -into the additional tracks, under the same clip. Note that the copy -will *not* keep its properties or state in sync with the original. - -Connect to this signal once if you wish to control which element -should be added to which track. Doing so will overwrite the default -behaviour, which adds @track_element to all tracks whose -#GESTrack:track-type includes the @track_element's -#GESTrackElement:track-type. - -Note that under the default track selection, if a clip would produce -multiple core children of the same #GESTrackType, it will choose -one of the core children arbitrarily to place in the corresponding -tracks, with a warning for the other core children that are not -placed in the track. For example, this would happen for a #GESUriClip -that points to a file that contains multiple audio streams. If you -wish to choose the stream, you could connect to this signal, and use, -say, ges_uri_source_asset_get_stream_info() to choose which core -source to add. - -When a clip is first added to a timeline, its core elements will -be created for the current tracks in the timeline if they have not -already been created. Then this will be emitted for each of these -core children to select which tracks, if any, they should be added -to. It will then be called for any non-core children in the clip. - -In addition, if a new track element is ever added to a clip in a -timeline (and it is not already part of a track) this will be emitted -to select which tracks the element should be added to. - -Finally, as a special case, if a track is added to the timeline -*after* it already contains clips, then it will request the creation -of the clips' core elements of the corresponding type, if they have -not already been created, and this signal will be emitted for each of -these newly created elements. In addition, this will also be released -for all other track elements in the timeline's clips that have not -yet been assigned a track. However, in this final case, the timeline -will only check whether the newly added track appears in the track -list. If it does appear, the track element will be added to the newly -added track. All other tracks in the returned track list are ignored. - -In this latter case, track elements that are already part of a track -will not be asked if they want to be copied into the new track. If -you wish to do this, you can use ges_clip_add_child_to_track(). - -Note that the returned #GPtrArray should own a new reference to each -of its contained #GESTrack. The timeline will set the #GDestroyNotify -free function on the #GPtrArray to dereference the elements. - - An array of -#GESTrack-s that @track_element should be added to, or %NULL to -not add the element to any track. - - - - - - - The clip that @track_element is being added to - - - - The element being added - - - - - - Will be emitted whenever a snapping event ends. After a snap event -has started (see #GESTimeline::snapping-started), it can later end -because either another timeline edit has occurred (which may or may -not have created a new snapping event), or because the timeline has -been committed. - - - - - - The first element that was snapping - - - - The second element that was snapping - - - - The position where the two objects were to be snapped to - - - - - - Will be emitted whenever an element's movement invokes a snapping -event during an edit (usually of one of its ancestors) because its -start or end point lies within the #GESTimeline:snapping-distance of -another element's start or end point. - -See #GESEditMode to see what can snap during an edit. - -Note that only up to one snapping-started signal will be emitted per -element edit within a timeline. - - - - - - The first element that is snapping - - - - The second element that is snapping - - - - The position where the two objects will snap to - - - - - - Will be emitted after the track is added to the timeline. - -Note that this should not be emitted whilst a timeline is being -loaded from its #GESProject asset. You should connect to the -project's #GESProject::loaded signal if you want to know which -tracks were created for the timeline. - - - - - - The track that was added to @timeline - - - - - - Will be emitted after the track is removed from the timeline. - - - - - - The track that was removed from @timeline - - - - - - - - - parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESTimelineElement will have some temporal extent in its -corresponding #GESTimelineElement:timeline, controlled by its -#GESTimelineElement:start and #GESTimelineElement:duration. This -determines when its content will be displayed, or its effect applied, -in the timeline. Several objects may overlap within a given -#GESTimeline, in which case their #GESTimelineElement:priority is used -to determine their ordering in the timeline. Priority is mostly handled -internally by #GESLayer-s and #GESClip-s. - -A timeline element can have a #GESTimelineElement:parent, -such as a #GESClip, which is responsible for controlling its timing. - -## Editing - -Elements can be moved around in their #GESTimelineElement:timeline by -setting their #GESTimelineElement:start and -#GESTimelineElement:duration using ges_timeline_element_set_start() -and ges_timeline_element_set_duration(). Additionally, which parts of -the underlying content are played in the timeline can be adjusted by -setting the #GESTimelineElement:in-point using -ges_timeline_element_set_inpoint(). The library also provides -ges_timeline_element_edit(), with various #GESEditMode-s, which can -adjust these properties in a convenient way, as well as introduce -similar changes in neighbouring or later elements in the timeline. - -However, a timeline may refuse a change in these properties if they -would place the timeline in an unsupported configuration. See -#GESTimeline for its overlap rules. - -Additionally, an edit may be refused if it would place one of the -timing properties out of bounds (such as a negative time value for -#GESTimelineElement:start, or having insufficient internal -content to last for the desired #GESTimelineElement:duration). - -## Time Coordinates - -There are three main sets of time coordinates to consider when using -timeline elements: - -+ Timeline coordinates: these are the time coordinates used in the - output of the timeline in its #GESTrack-s. Each track share the same - coordinates, so there is only one set of coordinates for the - timeline. These extend indefinitely from 0. The times used for - editing (including setting #GESTimelineElement:start and - #GESTimelineElement:duration) use these coordinates, since these - define when an element is present and for how long the element lasts - for in the timeline. -+ Internal source coordinates: these are the time coordinates used - internally at the element's output. This is only really defined for - #GESTrackElement-s, where it refers to time coordinates used at the - final source pad of the wrapped #GstElement-s. However, these - coordinates may also be used in a #GESClip in reference to its - children. In particular, these are the coordinates used for - #GESTimelineElement:in-point and #GESTimelineElement:max-duration. -+ Internal sink coordinates: these are the time coordinates used - internally at the element's input. A #GESSource has no input, so - these would be undefined. Otherwise, for most #GESTrackElement-s - these will be the same set of coordinates as the internal source - coordinates because the element does not change the timing - internally. Only #GESBaseEffect can support elements where these - are different. See #GESBaseEffect for more information. - -You can determine the timeline time for a given internal source time -in a #GESTrack in a #GESClip using -ges_clip_get_timeline_time_from_internal_time(), and vice versa using -ges_clip_get_internal_time_from_timeline_time(), for the purposes of -editing and setting timings properties. - -## Children Properties - -If a timeline element owns another #GstObject and wishes to expose -some of its properties, it can do so by registering the property as one -of the timeline element's children properties using -ges_timeline_element_add_child_property(). The registered property of -the child can then be read and set using the -ges_timeline_element_get_child_property() and -ges_timeline_element_set_child_property() methods, respectively. Some -sub-classed objects will be created with pre-registered children -properties; for example, to expose part of an underlying #GstElement -that is used internally. The registered properties can be listed with -ges_timeline_element_list_children_properties(). - - - - - - - - - - - - - - - - - - - Gets the priority of the layer the element is in. A #GESGroup may span -several layers, so this would return the highest priority (numerically, -the smallest) amongst them. - - - The priority of the layer @self is in, or -#GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY if @self does not exist in a -layer. - - - - - A #GESTimelineElement - - - - - - Get the "natural" framerate of @self. This is to say, for example -for a #GESVideoUriSource the framerate of the source. - -Note that a #GESAudioSource may also have a natural framerate if it derives -from the same #GESSourceClip asset as a #GESVideoSource, and its value will -be that of the video source. For example, if the uri of a #GESUriClip points -to a file that contains both a video and audio stream, then the corresponding -#GESAudioUriSource will share the natural framerate of the corresponding -#GESVideoUriSource. - - - Whether @self has a natural framerate or not, @framerate_n -and @framerate_d will be set to, respectively, 0 and -1 if it is -not the case. - - - - - The #GESTimelineElement to get "natural" framerate from - - - - The framerate numerator - - - - The framerate denominator - - - - - - Gets the track types that the element can interact with, i.e. the type -of #GESTrack it can exist in, or will create #GESTrackElement-s for. - - - The track types that @self supports. - - - - - A #GESTimelineElement - - - - - - - - - - - - - - - - - - - - Looks up a child property of the element. - -@prop_name can either be in the format "prop-name" or -"TypeName::prop-name", where "prop-name" is the name of the property -to look up (as used in g_object_get()), and "TypeName" is the type name -of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is -useful when two children of different types share the same property -name. - -The first child found with the given "prop-name" property that was -registered with ges_timeline_element_add_child_property() (and of the -type "TypeName", if it was given) will be passed to @child, and the -registered specification of this property will be passed to @pspec. - - - %TRUE if a child corresponding to the property was found, in -which case @child and @pspec are set. - - - - - A #GESTimelineElement - - - - The name of a child property - - - - The return location for the -found child - - - - The return location for the -specification of the child property - - - - - - - - - - - - - - - - - - - - - - - Edits the start time of an element within its timeline in ripple mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and -#GES_EDGE_NONE. - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new start time of @self in ripple mode - - - - - - Edits the end time of an element within its timeline in ripple mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and -#GES_EDGE_END. - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new end time of @self in ripple mode - - - - - - Edits the end time of an element within its timeline in roll mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and -#GES_EDGE_END. - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new end time of @self in roll mode - - - - - - Edits the start time of an element within its timeline in roll mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and -#GES_EDGE_START. - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new start time of @self in roll mode - - - - - - Method for setting the child property given by -@pspec on @child to @value. Default implementation will use -g_object_set_property(). - - - - - - - - - - - - - - - - - - - - - Similar to @set_child_property, except setting can fail, with the @error -being optionally set. Default implementation will call @set_child_property -and return %TRUE. - - - - - - - - - - - - - - - - - - - - - Sets #GESTimelineElement:duration for the element. - -Whilst the element is part of a #GESTimeline, this is the same as -editing the element with ges_timeline_element_edit() under -#GES_EDIT_MODE_TRIM with #GES_EDGE_END. In particular, the -#GESTimelineElement:duration of the element may be snapped to a -different timeline time difference from the one given. In addition, -setting may fail if it would place the timeline in an unsupported -configuration, or the element does not have enough internal content to -last the desired duration. - - - %TRUE if @duration could be set for @self. - - - - - A #GESTimelineElement - - - - The desired duration in its timeline - - - - - - Sets #GESTimelineElement:in-point for the element. If the new in-point -is above the current #GESTimelineElement:max-duration of the element, -this method will fail. - - - %TRUE if @inpoint could be set for @self. - - - - - A #GESTimelineElement - - - - The in-point, in internal time coordinates - - - - - - Sets #GESTimelineElement:max-duration for the element. If the new -maximum duration is below the current #GESTimelineElement:in-point of -the element, this method will fail. - - - %TRUE if @maxduration could be set for @self. - - - - - A #GESTimelineElement - - - - The maximum duration, in internal time coordinates - - - - - - Sets the #GESTimelineElement:parent for the element. - -This is used internally and you should normally not call this. A -#GESContainer will set the #GESTimelineElement:parent of its children -in ges_container_add() and ges_container_remove(). - -Note, if @parent is not %NULL, @self must not already have a parent -set. Therefore, if you wish to switch parents, you will need to call -this function twice: first to set the parent to %NULL, and then to the -new parent. - -If @parent is not %NULL, you must ensure it already has a -(non-floating) reference to @self before calling this. - - - %TRUE if @parent could be set for @self. - - - - - A #GESTimelineElement -@parent (nullable): New parent of @self - - - - - - - - - Sets the priority of the element within the containing layer. - All priority management is done by GES itself now. -To set #GESEffect priorities #ges_clip_set_top_effect_index should -be used. - - - %TRUE if @priority could be set for @self. - - - - - A #GESTimelineElement - - - - The priority - - - - - - Sets #GESTimelineElement:start for the element. If the element has a -parent, this will also move its siblings with the same shift. - -Whilst the element is part of a #GESTimeline, this is the same as -editing the element with ges_timeline_element_edit() under -#GES_EDIT_MODE_NORMAL with #GES_EDGE_NONE. In particular, the -#GESTimelineElement:start of the element may be snapped to a different -timeline time from the one given. In addition, setting may fail if it -would place the timeline in an unsupported configuration. - - - %TRUE if @start could be set for @self. - - - - - A #GESTimelineElement - - - - The desired start position of the element in its timeline - - - - - - Edits the start time of an element within its timeline in trim mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_TRIM and -#GES_EDGE_START. - - - %TRUE if the trim edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to trim - - - - The new start time of @self in trim mode - - - - - - Register a property of a child of the element to allow it to be -written with ges_timeline_element_set_child_property() and read with -ges_timeline_element_get_child_property(). A change in the property -will also appear in the #GESTimelineElement::deep-notify signal. - -@pspec should be unique from other children properties that have been -registered on @self. - - - %TRUE if the property was successfully registered. - - - - - A #GESTimelineElement - - - - The specification for the property to add - - - - The #GstObject who the property belongs to - - - - - - Create a copy of @self. All the properties of @self are copied into -a new element, with the exception of #GESTimelineElement:parent, -#GESTimelineElement:timeline and #GESTimelineElement:name. Other data, -such the list of a #GESContainer's children, is **not** copied. - -If @deep is %TRUE, then the new element is prepared so that it can be -used in ges_timeline_element_paste() or ges_timeline_paste_element(). -In the case of copying a #GESContainer, this ensures that the children -of @self will also be pasted. The new element should not be used for -anything else and can only be used **once** in a pasting operation. In -particular, the new element itself is not an actual 'deep' copy of -@self, but should be thought of as an intermediate object used for a -single paste operation. - - - The newly create element, -copied from @self. - - - - - The #GESTimelineElement to copy - - - - Whether the copy is needed for pasting - - - - - - See ges_timeline_element_edit_full(), which also gives an error. - -Note that the @layers argument is currently ignored, so you should -just pass %NULL. - - - %TRUE if the edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to edit - - - - A whitelist of layers -where the edit can be performed, %NULL allows all layers in the -timeline. - - - - - - The priority/index of the layer @self should be -moved to. -1 means no move - - - - The edit mode - - - - The edge of @self where the edit should occur - - - - The edit position: a new location for the edge of @self -(in nanoseconds) in the timeline coordinates - - - - - - Edits the element within its timeline by adjusting its -#GESTimelineElement:start, #GESTimelineElement:duration or -#GESTimelineElement:in-point, and potentially doing the same for -other elements in the timeline. See #GESEditMode for details about each -edit mode. An edit may fail if it would place one of these properties -out of bounds, or if it would place the timeline in an unsupported -configuration. - -Note that if you act on a #GESTrackElement, this will edit its parent -#GESClip instead. Moreover, for any #GESTimelineElement, if you select -#GES_EDGE_NONE for #GES_EDIT_MODE_NORMAL or #GES_EDIT_MODE_RIPPLE, this -will edit the toplevel instead, but still in such a way as to make the -#GESTimelineElement:start of @self reach the edit @position. - -Note that if the element's timeline has a -#GESTimeline:snapping-distance set, then the edit position may be -snapped to the edge of some element under the edited element. - -@new_layer_priority can be used to switch @self, and other elements -moved by the edit, to a new layer. New layers may be be created if the -the corresponding layer priority/index does not yet exist for the -timeline. - - - %TRUE if the edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to edit - - - - The priority/index of the layer @self should be -moved to. -1 means no move - - - - The edit mode - - - - The edge of @self where the edit should occur - - - - The edit position: a new location for the edge of @self -(in nanoseconds) in the timeline coordinates - - - - - - Gets several of the children properties of the element. See -ges_timeline_element_get_child_property(). - - - - - - - A #GESTimelineElement - - - - The name of the first child property to get - - - - The return location for the first property, followed -optionally by more name/return location pairs, followed by %NULL - - - - - - Gets the property of a child of the element. - -@property_name can either be in the format "prop-name" or -"TypeName::prop-name", where "prop-name" is the name of the property -to get (as used in g_object_get()), and "TypeName" is the type name of -the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is -useful when two children of different types share the same property -name. - -The first child found with the given "prop-name" property that was -registered with ges_timeline_element_add_child_property() (and of the -type "TypeName", if it was given) will have the corresponding -property copied into @value. - -Note that ges_timeline_element_get_child_properties() may be more -convenient for C programming. - - - %TRUE if the property was found and copied to @value. - - - - - A #GESTimelineElement - - - - The name of the child property to get - - - - The return location for the value - - - - - - Gets the property of a child of the element. Specifically, the property -corresponding to the @pspec used in -ges_timeline_element_add_child_property() is copied into @value. - - - - - - - A #GESTimelineElement - - - - The specification of a registered child property to get - - - - The return location for the value - - - - - - Gets several of the children properties of the element. See -ges_timeline_element_get_child_property(). - - - - - - - A #GESTimelineElement - - - - The name of the first child property to get - - - - The return location for the first property, followed -optionally by more name/return location pairs, followed by %NULL - - - - - - Gets the #GESTimelineElement:duration for the element. - - - The duration of @self (in nanoseconds). - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:in-point for the element. - - - The in-point of @self (in nanoseconds). - - - - - A #GESTimelineElement - - - - - - Gets the priority of the layer the element is in. A #GESGroup may span -several layers, so this would return the highest priority (numerically, -the smallest) amongst them. - - - The priority of the layer @self is in, or -#GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY if @self does not exist in a -layer. - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:max-duration for the element. - - - The max-duration of @self (in nanoseconds). - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:name for the element. - - - The name of @self. - - - - - A #GESTimelineElement - - - - - - Get the "natural" framerate of @self. This is to say, for example -for a #GESVideoUriSource the framerate of the source. - -Note that a #GESAudioSource may also have a natural framerate if it derives -from the same #GESSourceClip asset as a #GESVideoSource, and its value will -be that of the video source. For example, if the uri of a #GESUriClip points -to a file that contains both a video and audio stream, then the corresponding -#GESAudioUriSource will share the natural framerate of the corresponding -#GESVideoUriSource. - - - Whether @self has a natural framerate or not, @framerate_n -and @framerate_d will be set to, respectively, 0 and -1 if it is -not the case. - - - - - The #GESTimelineElement to get "natural" framerate from - - - - The framerate numerator - - - - The framerate denominator - - - - - - Gets the #GESTimelineElement:parent for the element. - - - The parent of @self, or %NULL if -@self has no parent. - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:priority for the element. - - - The priority of @self. - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:start for the element. - - - The start of @self (in nanoseconds). - - - - - A #GESTimelineElement - - - - - - Gets the #GESTimelineElement:timeline for the element. - - - The timeline of @self, or %NULL -if @self has no timeline. - - - - - A #GESTimelineElement - - - - - - Gets the toplevel #GESTimelineElement:parent of the element. - - - The toplevel parent of @self. - - - - - The #GESTimelineElement to get the toplevel parent from - - - - - - Gets the track types that the element can interact with, i.e. the type -of #GESTrack it can exist in, or will create #GESTrackElement-s for. - - - The track types that @self supports. - - - - - A #GESTimelineElement - - - - - - Get a list of children properties of the element, which is a list of -all the specifications passed to -ges_timeline_element_add_child_property(). - - - An array of -#GParamSpec corresponding to the child properties of @self, or %NULL if -something went wrong. - - - - - - - A #GESTimelineElement - - - - The return location for the length of the -returned array - - - - - - Looks up a child property of the element. - -@prop_name can either be in the format "prop-name" or -"TypeName::prop-name", where "prop-name" is the name of the property -to look up (as used in g_object_get()), and "TypeName" is the type name -of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is -useful when two children of different types share the same property -name. - -The first child found with the given "prop-name" property that was -registered with ges_timeline_element_add_child_property() (and of the -type "TypeName", if it was given) will be passed to @child, and the -registered specification of this property will be passed to @pspec. - - - %TRUE if a child corresponding to the property was found, in -which case @child and @pspec are set. - - - - - A #GESTimelineElement - - - - The name of a child property - - - - The return location for the -found child - - - - The return location for the -specification of the child property - - - - - - Paste an element inside the same timeline and layer as @self. @self -**must** be the return of ges_timeline_element_copy() with `deep=TRUE`, -and it should not be changed before pasting. -@self is not placed in the timeline, instead a new element is created, -alike to the originally copied element. Note that the originally -copied element must stay within the same timeline and layer, at both -the point of copying and pasting. - -Pasting may fail if it would place the timeline in an unsupported -configuration. - -After calling this function @element should not be used. In particular, -@element can **not** be pasted again. Instead, you can copy the -returned element and paste that copy (although, this is only possible -if the paste was successful). - -See also ges_timeline_paste_element(). - - - The newly created element, or -%NULL if pasting fails. - - - - - The #GESTimelineElement to paste - - - - The position in the timeline @element should be pasted -to, i.e. the #GESTimelineElement:start value for the pasted element. - - - - - - Remove a child property from the element. @pspec should be a -specification that was passed to -ges_timeline_element_add_child_property(). The corresponding property -will no longer be registered as a child property for the element. - - - %TRUE if the property was successfully un-registered for @self. - - - - - A #GESTimelineElement - - - - The specification for the property to remove - - - - - - Edits the start time of an element within its timeline in ripple mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and -#GES_EDGE_NONE. - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new start time of @self in ripple mode - - - - - - Edits the end time of an element within its timeline in ripple mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_RIPPLE and -#GES_EDGE_END. - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new end time of @self in ripple mode - - - - - - Edits the end time of an element within its timeline in roll mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and -#GES_EDGE_END. - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new end time of @self in roll mode - - - - - - Edits the start time of an element within its timeline in roll mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_ROLL and -#GES_EDGE_START. - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new start time of @self in roll mode - - - - - - Sets several of the children properties of the element. See -ges_timeline_element_set_child_property(). - - - - - - - A #GESTimelineElement - - - - The name of the first child property to set - - - - The value for the first property, followed optionally by more -name/value pairs, followed by %NULL - - - - - - See ges_timeline_element_set_child_property_full(), which also gives an -error. - -Note that ges_timeline_element_set_child_properties() may be more -convenient for C programming. - - - %TRUE if the property was found and set. - - - - - A #GESTimelineElement - - - - The name of the child property to set - - - - The value to set the property to - - - - - - Sets the property of a child of the element. Specifically, the property -corresponding to the @pspec used in -ges_timeline_element_add_child_property() is set to @value. - - - - - - - A #GESTimelineElement - - - - The specification of a registered child property to set - - - - The value to set the property to - - - - - - Sets the property of a child of the element. - -@property_name can either be in the format "prop-name" or -"TypeName::prop-name", where "prop-name" is the name of the property -to set (as used in g_object_set()), and "TypeName" is the type name of -the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is -useful when two children of different types share the same property -name. - -The first child found with the given "prop-name" property that was -registered with ges_timeline_element_add_child_property() (and of the -type "TypeName", if it was given) will have the corresponding -property set to @value. Other children that may have also matched the -property name (and type name) are left unchanged! - - - %TRUE if the property was found and set. - - - - - A #GESTimelineElement - - - - The name of the child property to set - - - - The value to set the property to - - - - - - Sets several of the children properties of the element. See -ges_timeline_element_set_child_property(). - - - - - - - A #GESTimelineElement - - - - The name of the first child property to set - - - - The value for the first property, followed optionally by more -name/value pairs, followed by %NULL - - - - - - Sets #GESTimelineElement:duration for the element. - -Whilst the element is part of a #GESTimeline, this is the same as -editing the element with ges_timeline_element_edit() under -#GES_EDIT_MODE_TRIM with #GES_EDGE_END. In particular, the -#GESTimelineElement:duration of the element may be snapped to a -different timeline time difference from the one given. In addition, -setting may fail if it would place the timeline in an unsupported -configuration, or the element does not have enough internal content to -last the desired duration. - - - %TRUE if @duration could be set for @self. - - - - - A #GESTimelineElement - - - - The desired duration in its timeline - - - - - - Sets #GESTimelineElement:in-point for the element. If the new in-point -is above the current #GESTimelineElement:max-duration of the element, -this method will fail. - - - %TRUE if @inpoint could be set for @self. - - - - - A #GESTimelineElement - - - - The in-point, in internal time coordinates - - - - - - Sets #GESTimelineElement:max-duration for the element. If the new -maximum duration is below the current #GESTimelineElement:in-point of -the element, this method will fail. - - - %TRUE if @maxduration could be set for @self. - - - - - A #GESTimelineElement - - - - The maximum duration, in internal time coordinates - - - - - - Sets the #GESTimelineElement:name for the element. If %NULL is given -for @name, then the library will instead generate a new name based on -the type name of the element, such as the name "uriclip3" for a -#GESUriClip, and will set that name instead. - -If @self already has a #GESTimelineElement:timeline, you should not -call this function with @name set to %NULL. - -You should ensure that, within each #GESTimeline, every element has a -unique name. If you call this function with @name as %NULL, then -the library should ensure that the set generated name is unique from -previously **generated** names. However, if you choose a @name that -interferes with the naming conventions of the library, the library will -attempt to ensure that the generated names will not conflict with the -chosen name, which may lead to a different name being set instead, but -the uniqueness between generated and user-chosen names is not -guaranteed. - - - %TRUE if @name or a generated name for @self could be set. - - - - - A #GESTimelineElement - - - - The name @self should take - - - - - - Sets the #GESTimelineElement:parent for the element. - -This is used internally and you should normally not call this. A -#GESContainer will set the #GESTimelineElement:parent of its children -in ges_container_add() and ges_container_remove(). - -Note, if @parent is not %NULL, @self must not already have a parent -set. Therefore, if you wish to switch parents, you will need to call -this function twice: first to set the parent to %NULL, and then to the -new parent. - -If @parent is not %NULL, you must ensure it already has a -(non-floating) reference to @self before calling this. - - - %TRUE if @parent could be set for @self. - - - - - A #GESTimelineElement -@parent (nullable): New parent of @self - - - - - - - - - Sets the priority of the element within the containing layer. - All priority management is done by GES itself now. -To set #GESEffect priorities #ges_clip_set_top_effect_index should -be used. - - - %TRUE if @priority could be set for @self. - - - - - A #GESTimelineElement - - - - The priority - - - - - - Sets #GESTimelineElement:start for the element. If the element has a -parent, this will also move its siblings with the same shift. - -Whilst the element is part of a #GESTimeline, this is the same as -editing the element with ges_timeline_element_edit() under -#GES_EDIT_MODE_NORMAL with #GES_EDGE_NONE. In particular, the -#GESTimelineElement:start of the element may be snapped to a different -timeline time from the one given. In addition, setting may fail if it -would place the timeline in an unsupported configuration. - - - %TRUE if @start could be set for @self. - - - - - A #GESTimelineElement - - - - The desired start position of the element in its timeline - - - - - - Sets the #GESTimelineElement:timeline of the element. - -This is used internally and you should normally not call this. A -#GESClip will have its #GESTimelineElement:timeline set through its -#GESLayer. A #GESTrack will similarly take care of setting the -#GESTimelineElement:timeline of its #GESTrackElement-s. A #GESGroup -will adopt the same #GESTimelineElement:timeline as its children. - -If @timeline is %NULL, this will stop its current -#GESTimelineElement:timeline from tracking it, otherwise @timeline will -start tracking @self. Note, in the latter case, @self must not already -have a timeline set. Therefore, if you wish to switch timelines, you -will need to call this function twice: first to set the timeline to -%NULL, and then to the new timeline. - - - %TRUE if @timeline could be set for @self. - - - - - A #GESTimelineElement -@timeline (nullable): The #GESTimeline @self should be in - - - - - - - - - Edits the start time of an element within its timeline in trim mode. -See ges_timeline_element_edit() with #GES_EDIT_MODE_TRIM and -#GES_EDGE_START. - - - %TRUE if the trim edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to trim - - - - The new start time of @self in trim mode - - - - - - The duration that the element is in effect for in the timeline (a -time difference in nanoseconds using the time coordinates of the -timeline). For example, for a source element, this would determine -for how long it should output its internal content for. For an -operation element, this would determine for how long its effect -should be applied to any source content. - - - - The initial offset to use internally when outputting content (in -nanoseconds, but in the time coordinates of the internal content). - -For example, for a #GESVideoUriSource that references some media -file, the "internal content" is the media file data, and the -in-point would correspond to some timestamp in the media file. -When playing the timeline, and when the element is first reached at -timeline-time #GESTimelineElement:start, it will begin outputting the -data from the timestamp in-point **onwards**, until it reaches the -end of its #GESTimelineElement:duration in the timeline. - -For elements that have no internal content, this should be kept -as 0. - - - - The full duration of internal content that is available (a time -difference in nanoseconds using the time coordinates of the internal -content). - -This will act as a cap on the #GESTimelineElement:in-point of the -element (which is in the same time coordinates), and will sometimes -be used to limit the #GESTimelineElement:duration of the element in -the timeline. - -For example, for a #GESVideoUriSource that references some media -file, this would be the length of the media file. - -For elements that have no internal content, or whose content is -indefinite, this should be kept as #GST_CLOCK_TIME_NONE. - - - - The name of the element. This should be unique within its timeline. - - - - The parent container of the element. - - - - The priority of the element. - Priority management is now done by GES itself. - - - - Whether the element should be serialized. - - - - The starting position of the element in the timeline (in nanoseconds -and in the time coordinates of the timeline). For example, for a -source element, this would determine the time at which it should -start outputting its internal content. For an operation element, this -would determine the time at which it should start applying its effect -to any source content. - - - - The timeline that the element lies within. - - - - - - - The #GESTimelineElement:parent of the element - - - - The #GESAsset from which the object has been extracted - - - - The #GESTimelineElement:start of the element - - - - The #GESTimelineElement:in-point of the element - - - - The #GESTimelineElement:duration of the element - - - - The #GESTimelineElement:max-duration of the element - - - - The #GESTimelineElement:priority of the element - - - - The #GESTimelineElement:timeline of the element - - - - The #GESTimelineElement:name of the element - - - - - - - - - - - - Emitted when the element has a new child property registered. See -ges_timeline_element_add_child_property(). - -Note that some GES elements will be automatically created with -pre-registered children properties. You can use -ges_timeline_element_list_children_properties() to list these. - - - - - - The child whose property has been registered - - - - The specification for the property that has been registered - - - - - - Emitted when the element has a child property unregistered. See -ges_timeline_element_remove_child_property(). - - - - - - The child whose property has been unregistered - - - - The specification for the property that has been unregistered - - - - - - Emitted when a child of the element has one of its registered -properties set. See ges_timeline_element_add_child_property(). -Note that unlike #GObject::notify, a child property name can not be -used as a signal detail. - - - - - - The child whose property has been set - - - - The specification for the property that been set - - - - - - - The #GESTimelineElement base class. Subclasses should override at least -@set_start @set_inpoint @set_duration @ripple @ripple_end @roll_start -@roll_end and @trim. - -Vmethods in subclasses should apply all the operation they need to but -the real method implementation is in charge of setting the proper field, -and emitting the notify signal. - - - - - - - - - %TRUE if @parent could be set for @self. - - - - - A #GESTimelineElement -@parent (nullable): New parent of @self - - - - - - - - - - - - - %TRUE if @start could be set for @self. - - - - - A #GESTimelineElement - - - - The desired start position of the element in its timeline - - - - - - - - - - %TRUE if @inpoint could be set for @self. - - - - - A #GESTimelineElement - - - - The in-point, in internal time coordinates - - - - - - - - - - %TRUE if @duration could be set for @self. - - - - - A #GESTimelineElement - - - - The desired duration in its timeline - - - - - - - - - - %TRUE if @maxduration could be set for @self. - - - - - A #GESTimelineElement - - - - The maximum duration, in internal time coordinates - - - - - - - - - - %TRUE if @priority could be set for @self. - - - - - A #GESTimelineElement - - - - The priority - - - - - - - - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new start time of @self in ripple mode - - - - - - - - - - %TRUE if the ripple edit of @self completed, %FALSE on -failure. - - - - - The #GESTimelineElement to ripple - - - - The new end time of @self in ripple mode - - - - - - - - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new start time of @self in roll mode - - - - - - - - - - %TRUE if the roll edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to roll - - - - The new end time of @self in roll mode - - - - - - - - - - %TRUE if the trim edit of @self completed, %FALSE on failure. - - - - - The #GESTimelineElement to trim - - - - The new start time of @self in trim mode - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if a child corresponding to the property was found, in -which case @child and @pspec are set. - - - - - A #GESTimelineElement - - - - The name of a child property - - - - The return location for the -found child - - - - The return location for the -specification of the child property - - - - - - - - - - The track types that @self supports. - - - - - A #GESTimelineElement - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The priority of the layer @self is in, or -#GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY if @self does not exist in a -layer. - - - - - A #GESTimelineElement - - - - - - - - - - Whether @self has a natural framerate or not, @framerate_n -and @framerate_d will be set to, respectively, 0 and -1 if it is -not the case. - - - - - The #GESTimelineElement to get "natural" framerate from - - - - The framerate numerator - - - - The framerate denominator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Renders the given text in the specified font, at specified position, and -with the specified background pattern. - - - - - Creates a new #GESTitleClip - - - The newly created #GESTitleClip, -or %NULL if there was an error. - - - - - Get the background used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The color used by @self. - - - - - a #GESTitleClip - - - - - - Get the pango font description used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The pango font description used by @self. - - - - - a #GESTitleClip - - - - - - Get the horizontal aligment used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The horizontal aligment used by @self. - - - - - a #GESTitleClip - - - - - - Get the text currently set on @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The text currently set on @self. - - - - - a #GESTitleClip - - - - - - Get the color used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The color used by @self. - - - - - a #GESTitleClip - - - - - - Get the vertical aligment used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The vertical aligment used by @self. - - - - - a #GESTitleClip - - - - - - Get the horizontal position used by @self. - use #ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - The horizontal position used by @self. - - - - - a #GESTitleClip - - - - - - Get the vertical position used by @self. - use #ges_timeline_element_get_children_property instead - - - The vertical position used by @self. - - - - - a #GESTitleClip - - - - - - Sets the background of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set - - - - The color @self is being set to - - - - - - Sets the color of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set - - - - The color @self is being set to - - - - - - Sets the pango font description of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* - - - - the pango font description - - - - - - Sets the horizontal aligment of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set horizontal alignement of text on - - - - #GESTextHAlign - - - - - - Sets the text this clip will render. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set text on - - - - the text to render. an internal copy of this text will be -made. - - - - - - Sets the vertical aligment of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set vertical alignement of text on - - - - #GESTextVAlign - - - - - - Sets the horizontal position of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set - - - - The horizontal position @self is being set to - - - - - - Sets the vertical position of the text. - use #ges_timeline_element_set_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - the #GESTitleClip* to set - - - - The vertical position @self is being set to - - - - - - The background of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - The color of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - Pango font description string - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - Horizontal alignment of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - The text to diplay - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - Vertical alignent of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - The horizontal position of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - The vertical position of the text - use #ges_timeline_element_set_children_properties or -#ges_timeline_element_get_children_properties instead. -See #GESTitleSource for more information about exposed properties - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GESTitleSource is a GESTimelineElement that implements the notion -of titles in GES. - - - - - Get the background used by @source. - - - The background used by @source. - - - - - a #GESTitleSource - - - - - - Get the pango font description used by @source. - Use ges_timeline_element_get_child_property instead -(this actually returns a newly allocated string) - - - The pango font description used by this -@source. - - - - - a #GESTitleSource - - - - - - Get the horizontal aligment used by @source. - - - The horizontal aligment used by @source. - - - - - a #GESTitleSource - - - - - - Get the text currently set on the @source. - Use ges_timeline_element_get_child_property instead -(this actually returns a newly allocated string) - - - The text currently set on the @source. - - - - - a #GESTitleSource - - - - - - Get the color used by @source. - - - The color used by @source. - - - - - a #GESTitleSource - - - - - - Get the vertical aligment used by @source. - - - The vertical aligment used by @source. - - - - - a #GESTitleSource - - - - - - Get the horizontal position used by @source. - - - The horizontal position used by @source. - - - - - a #GESTitleSource - - - - - - Get the vertical position used by @source. - - - The vertical position used by @source. - - - - - a #GESTitleSource - - - - - - Sets the color of the background - - - - - - - the #GESTitleSource* to set - - - - the color @self is being set to - - - - - - Set the pango font description this source will use to render -the text. - - - - - - - the #GESTitleSource - - - - the pango font description - - - - - - Sets the vertical aligment of the text. - - - - - - - the #GESTitleSource* to set text on - - - - #GESTextHAlign - - - - - - Sets the text this track element will render. - use ges_track_element_get/set_children_properties on the -GESTrackElement instead - - - - - - - the #GESTitleSource* to set text on - - - - the text to render. an internal copy of this text will be -made. - - - - - - Sets the color of the text. - - - - - - - the #GESTitleSource* to set - - - - the color @self is being set to - - - - - - Sets the vertical aligment of the text. - - - - - - - the #GESTitleSource* to set text on - - - - #GESTextVAlign - - - - - - Sets the horizontal position of the text. - - - - - - - the #GESTitleSource* to set - - - - the horizontal position @self is being set to - - - - - - Sets the vertical position of the text. - - - - - - - the #GESTitleSource* to set - - - - the color @self is being set to - - - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - - - - A #GESTrack acts an output source for a #GESTimeline. Each one -essentially provides an additional #GstPad for the timeline, with -#GESTrack:restriction-caps capabilities. Internally, a track -wraps an #nlecomposition filtered by a #capsfilter. - -A track will contain a number of #GESTrackElement-s, and its role is -to select and activate these elements according to their timings when -the timeline in played. For example, a track would activate a -#GESSource when its #GESTimelineElement:start is reached by outputting -its data for its #GESTimelineElement:duration. Similarly, a -#GESOperation would be activated by applying its effect to the source -data, starting from its #GESTimelineElement:start time and lasting for -its #GESTimelineElement:duration. - -For most users, it will usually be sufficient to add newly created -tracks to a timeline, but never directly add an element to a track. -Whenever a #GESClip is added to a timeline, the clip adds its -elements to the timeline's tracks and assumes responsibility for -updating them. - - - - - Creates a new track with the given track-type and caps. - -If @type is #GES_TRACK_TYPE_VIDEO, and @caps is a subset of -"video/x-raw(ANY)", then a #GESVideoTrack is created. This will -automatically choose a gap creation method suitable for video data. You -will likely want to set #GESTrack:restriction-caps separately. You may -prefer to use the ges_video_track_new() method instead. - -If @type is #GES_TRACK_TYPE_AUDIO, and @caps is a subset of -"audio/x-raw(ANY)", then a #GESAudioTrack is created. This will -automatically choose a gap creation method suitable for audio data, and -will set the #GESTrack:restriction-caps to the default for -#GESAudioTrack. You may prefer to use the ges_audio_track_new() method -instead. - -Otherwise, a plain #GESTrack is returned. You will likely want to set -the #GESTrack:restriction-caps and call -ges_track_set_create_element_for_gap_func() on the returned track. - - - A new track. - - - - - The #GESTrack:track-type for the track - - - - The #GESTrack:caps for the track - - - - - - - - - - - - - - - - - See ges_track_add_element(), which also gives an error. - - - %TRUE if @object was successfully added to @track. - - - - - A #GESTrack - - - - The element to add - - - - - - Adds the given track element to the track, which takes ownership of the -element. - -Note that this can fail if it would break a configuration rule of the -track's #GESTimeline. - -Note that a #GESTrackElement can only be added to one track. - - - %TRUE if @object was successfully added to @track. - - - - - A #GESTrack - - - - The element to add - - - - - - Commits all the pending changes for the elements contained in the -track. - -When changes are made to the timing or priority of elements within a -track, they are not directly executed for the underlying -#nlecomposition and its children. This method will finally execute -these changes so they are reflected in the data output of the track. - -Any pending changes will be executed in the backend. The -#GESTimeline::commited signal will be emitted once this has completed. - -Note that ges_timeline_commit() will call this method on all of its -tracks, so you are unlikely to need to use this directly. - - - %TRUE if pending changes were committed, or %FALSE if nothing -needed to be committed. - - - - - A #GESTrack - - - - - - Get the #GESTrack:caps of the track. - - - The caps of @track. - - - - - A #GESTrack - - - - - - Gets the track elements contained in the track. The returned list is -sorted by the element's #GESTimelineElement:priority and -#GESTimelineElement:start. - - - A list of -all the #GESTrackElement-s in @track. - - - - - - - A #GESTrack - - - - - - Gets the #GESTrack:mixing of the track. - - - Whether @track is mixing. - - - - - A #GESTrack - - - - - - Gets the #GESTrack:restriction-caps of the track. - - - The restriction-caps of @track. - - - - - A #GESTrack - - - - - - Get the timeline this track belongs to. - - - The timeline that @track belongs to, or %NULL if -it does not belong to a timeline. - - - - - A #GESTrack - - - - - - See ges_track_remove_element_full(), which also returns an error. - - - %TRUE if @object was successfully removed from @track. - - - - - A #GESTrack - - - - The element to remove - - - - - - Removes the given track element from the track, which revokes -ownership of the element. - - - %TRUE if @object was successfully removed from @track. - - - - - A #GESTrack - - - - The element to remove - - - - - - Sets the function that will be used to create a #GstElement that can be -used as a source to fill the gaps of the track. A gap is a timeline -region where the track has no #GESTrackElement sources. Therefore, you -are likely to want the #GstElement returned by the function to always -produce 'empty' content, defined relative to the stream type, such as -transparent frames for a video, or mute samples for audio. - -#GESAudioTrack and #GESVideoTrack objects are created with such a -function already set appropriately. - - - - - - - A #GESTrack - - - - The function to be used to create a source -#GstElement that can fill gaps in @track - - - - - - Sets the #GESTrack:mixing for the track. - - - - - - - A #GESTrack - - - - Whether @track should be mixing - - - - - - Sets the #GESTrack:restriction-caps for the track. - -> **NOTE**: Restriction caps are **not** taken into account when -> using #GESPipeline:mode=#GES_PIPELINE_MODE_SMART_RENDER. - - - - - - - A #GESTrack - - - - The new restriction-caps for @track - - - - - - Informs the track that it belongs to the given timeline. Calling this -does not actually add the track to the timeline. For that, you should -use ges_timeline_add_track(), which will also take care of informing -the track that it belongs to the timeline. As such, there is no need -for you to call this method. - - - - - - - A #GESTrack -@timeline (nullable): A #GESTimeline - - - - - - - - - Updates the #GESTrack:restriction-caps of the track using the fields -found in the given caps. Each of the #GstStructure-s in @caps is -compared against the existing structure with the same index in the -current #GESTrack:restriction-caps. If there is no corresponding -existing structure at that index, then the new structure is simply -copied to that index. Otherwise, any fields in the new structure are -copied into the existing structure. This will replace existing values, -and may introduce new ones, but any fields 'missing' in the new -structure are left unchanged in the existing structure. - -For example, if the existing #GESTrack:restriction-caps are -"video/x-raw, width=480, height=360", and the updating caps is -"video/x-raw, format=I420, width=500; video/x-bayer, width=400", then -the new #GESTrack:restriction-caps after calling this will be -"video/x-raw, width=500, height=360, format=I420; video/x-bayer, -width=400". - - - - - - - A #GESTrack - - - - The caps to update the restriction-caps with - - - - - - The capabilities used to choose the output of the #GESTrack's -elements. Internally, this is used to select output streams when -several may be available, by determining whether its #GstPad is -compatible (see #NleObject:caps for #nlecomposition). As such, -this is used as a weaker indication of the desired output type of the -track, **before** the #GESTrack:restriction-caps is applied. -Therefore, this should be set to a *generic* superset of the -#GESTrack:restriction-caps, such as "video/x-raw(ANY)". In addition, -it should match with the track's #GESTrack:track-type. - -Note that when you set this property, the #GstCapsFeatures of all its -#GstStructure-s will be automatically set to #GST_CAPS_FEATURES_ANY. - -Once a track has been added to a #GESTimeline, you should not change -this. - -Default value: #GST_CAPS_ANY. - - - - Current duration of the track - -Default value: O - - - - The #nlecomposition:id of the underlying #nlecomposition. - - - - Whether the track should support the mixing of #GESLayer data, such -as composing the video data of each layer (when part of the video -data is transparent, the next layer will become visible) or adding -together the audio data. As such, for audio and video tracks, you'll -likely want to keep this set to %TRUE. - - - - The capabilities that specifies the final output format of the -#GESTrack. For example, for a video track, it would specify the -height, width, framerate and other properties of the stream. - -You may change this property after the track has been added to a -#GESTimeline, but it must remain compatible with the track's -#GESTrack:caps. - -Default value: #GST_CAPS_ANY. - - - - The track type of the track. This controls the type of -#GESTrackElement-s that can be added to the track. This should -match with the track's #GESTrack:caps. - -Once a track has been added to a #GESTimeline, you should not change -this. - - - - - - - The #GESTrack:track-type of the track - - - - - - - - - - - - This signal will be emitted once the changes initiated by -ges_track_commit() have been executed in the backend. In particular, -this will be emitted whenever the underlying #nlecomposition has been -committed (see #nlecomposition::commited). - - - - - - Will be emitted after a track element is added to the track. - - - - - - The element that was added - - - - - - Will be emitted after a track element is removed from the track. - - - - - - The element that was removed - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESTrackElement is a #GESTimelineElement that specifically belongs -to a single #GESTrack of its #GESTimelineElement:timeline. Its -#GESTimelineElement:start and #GESTimelineElement:duration specify its -temporal extent in the track. Specifically, a track element wraps some -nleobject, such as an #nlesource or #nleoperation, which can be -retrieved with ges_track_element_get_nleobject(), and its -#GESTimelineElement:start, #GESTimelineElement:duration, -#GESTimelineElement:in-point, #GESTimelineElement:priority and -#GESTrackElement:active properties expose the corresponding nleobject -properties. When a track element is added to a track, its nleobject is -added to the corresponding #nlecomposition that the track wraps. - -Most users will not have to work directly with track elements since a -#GESClip will automatically create track elements for its timeline's -tracks and take responsibility for updating them. The only track -elements that are not automatically created by clips, but a user is -likely to want to create, are #GESEffect-s. - -## Control Bindings for Children Properties - -You can set up control bindings for a track element child property -using ges_track_element_set_control_source(). A -#GstTimedValueControlSource should specify the timed values using the -internal source coordinates (see #GESTimelineElement). By default, -these will be updated to lie between the #GESTimelineElement:in-point -and out-point of the element. This can be switched off by setting -#GESTrackElement:auto-clamp-control-sources to %FALSE. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Looks up which @element and @pspec would be effected by the given @name. If various -contained elements have this property name you will get the first one, unless you -specify the class name in @name. - Use #ges_timeline_element_lookup_child - - - TRUE if @element and @pspec could be found. FALSE otherwise. In that -case the values for @pspec and @element are not modified. Unref @element after -usage. - - - - - Object to lookup the property in - - - - Name of the property to look up. You can specify the name of the - class as such: "ClassName::property-name", to guarantee that you get the - proper GParamSpec in case various GstElement-s contain the same property - name. If you don't do so, you will get the first element found, having - this property and the and the corresponding GParamSpec. - - - - pointer to a #GstElement that - takes the real object to set property on - - - - pointer to take the specification - describing the property - - - - - - Adds all the properties of a #GstElement that match the criteria as -children properties of the track element. If the name of @element's -#GstElementFactory is not in @blacklist, and the factory's -#GST_ELEMENT_METADATA_KLASS contains at least one member of -@wanted_categories (e.g. #GST_ELEMENT_FACTORY_KLASS_DECODER), then -all the properties of @element that are also in @whitelist are added as -child properties of @self using -ges_timeline_element_add_child_property(). - -This is intended to be used by subclasses when constructing. - - - - - - - A #GESTrackElement - - - - The child object to retrieve properties from - - - - -An array of element factory "klass" categories to whitelist, or %NULL -to accept all categories - - - - - - A -blacklist of element factory names, or %NULL to not blacklist any -element factory - - - - - - A -whitelist of element property names, or %NULL to whitelist all -writeable properties - - - - - - - - Clamp the #GstTimedValueControlSource for the specified child property -to lie between the #GESTimelineElement:in-point and out-point of the -element. The out-point is the #GES_TIMELINE_ELEMENT_END of the element -translated from the timeline coordinates to the internal source -coordinates of the element. - -If the property does not have a #GstTimedValueControlSource set by -ges_track_element_set_control_source(), nothing happens. Otherwise, if -a timed value for the control source lies before the in-point of the -element, or after its out-point, then it will be removed. At the -in-point and out-point times, a new interpolated value will be placed. - - - - - - - A #GESTrackElement - - - - The name of the child property to clamp the control -source of - - - - - - Edits the element within its track. - use #ges_timeline_element_edit instead. - - - %TRUE if the edit of @object completed, %FALSE on failure. - - - - - The #GESTrackElement to edit - - - - A whitelist of layers -where the edit can be performed, %NULL allows all layers in the -timeline - - - - - - The edit mode - - - - The edge of @object where the edit should occur - - - - The edit position: a new location for the edge of @object -(in nanoseconds) - - - - - - Get all the control bindings that have been created for the children -properties of the track element using -ges_track_element_set_control_source(). The keys used in the returned -hash table are the child property names that were passed to -ges_track_element_set_control_source(), and their values are the -corresponding created #GstControlBinding. - - - A -hash table containing all child-property-name/control-binding pairs -for @trackelement. - - - - - - - - A #GESTrackElement - - - - - - Gets #GESTrackElement:auto-clamp-control-sources. - - - Whether the control sources for the child properties of -@object are automatically clamped. - - - - - A #GESTrackElement - - - - - - Gets properties of a child of @object. - Use #ges_timeline_element_get_child_properties - - - - - - - The origin #GESTrackElement - - - - The name of the first property to get - - - - return location for the first property, followed optionally by more -name/return location pairs, followed by NULL - - - - - - In general, a copy is made of the property contents and -the caller is responsible for freeing the memory by calling -g_value_unset(). - -Gets a property of a GstElement contained in @object. - -Note that #ges_track_element_get_child_property is really -intended for language bindings, #ges_track_element_get_child_properties -is much more convenient for C programming. - Use #ges_timeline_element_get_child_property - - - %TRUE if the property was found, %FALSE otherwise. - - - - - The origin #GESTrackElement - - - - The name of the property - - - - return location for the property value, it will -be initialized if it is initialized with 0 - - - - - - Gets a property of a child of @object. - Use #ges_timeline_element_get_child_property_by_pspec - - - - - - - A #GESTrackElement - - - - The #GParamSpec that specifies the property you want to get - - - - return location for the value - - - - - - Gets a property of a child of @object. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. - Use #ges_timeline_element_get_child_property_valist - - - - - - - The #GESTrackElement parent object - - - - The name of the first property to get - - - - Value for the first property, followed optionally by more -name/return location pairs, followed by NULL - - - - - - Gets the control binding that was created for the specified child -property of the track element using -ges_track_element_set_control_source(). The given @property_name must -be the same name of the child property that was passed to -ges_track_element_set_control_source(). - - - The control binding that was -created for the specified child property of @object, or %NULL if -@property_name does not correspond to any control binding. - - - - - A #GESTrackElement - - - - The name of the child property to return the control -binding of - - - - - - Get the #GstElement that the track element's underlying nleobject -controls. - - - The #GstElement being controlled by the -nleobject that @object wraps. - - - - - A #GESTrackElement - - - - - - Get the GNonLin object this object is controlling. - use #ges_track_element_get_nleobject instead. - - - The GNonLin object this object is controlling. - - - - - A #GESTrackElement - - - - - - Get the nleobject that this element wraps. - - - The nleobject that @object wraps. - - - - - A #GESTrackElement - - - - - - Get the #GESTrackElement:track for the element. - - - The track that @object belongs to, -or %NULL if it does not belong to a track. - - - - - A #GESTrackElement - - - - - - Gets the #GESTrackElement:track-type for the element. - - - The track-type of @object. - - - - - A #GESTrackElement - - - - - - Gets #GESTrackElement:has-internal-source for the element. - - - %TRUE if @object can have its 'internal time' properties set. - - - - - A #GESTrackElement - - - - - - Gets #GESTrackElement:active for the element. - - - %TRUE if @object is active in its track. - - - - - A #GESTrackElement - - - - - - Get whether the given track element is a core track element. That is, -it was created by the @create_track_elements #GESClipClass method for -some #GESClip. - -Note that such a track element can only be added to a clip that shares -the same #GESAsset as the clip that created it. For example, you are -allowed to move core children between clips that resulted from -ges_container_ungroup(), but you could not move the core child from a -#GESUriClip to a #GESTitleClip or another #GESUriClip with a different -#GESUriClip:uri. - -Moreover, if a core track element is added to a clip, it will always be -added as a core child. Therefore, if this returns %TRUE, then @element -will be a core child of its parent clip. - - - %TRUE if @element is a core track element. - - - - - A #GESTrackElement - - - - - - Gets an array of #GParamSpec* for all configurable properties of the -children of @object. - Use #ges_timeline_element_list_children_properties - - - An array of #GParamSpec* which should be freed after use or -%NULL if something went wrong. - - - - - - - The #GESTrackElement to get the list of children properties from - - - - return location for the length of the returned array - - - - - - Looks up which @element and @pspec would be effected by the given @name. If various -contained elements have this property name you will get the first one, unless you -specify the class name in @name. - Use #ges_timeline_element_lookup_child - - - TRUE if @element and @pspec could be found. FALSE otherwise. In that -case the values for @pspec and @element are not modified. Unref @element after -usage. - - - - - Object to lookup the property in - - - - Name of the property to look up. You can specify the name of the - class as such: "ClassName::property-name", to guarantee that you get the - proper GParamSpec in case various GstElement-s contain the same property - name. If you don't do so, you will get the first element found, having - this property and the and the corresponding GParamSpec. - - - - pointer to a #GstElement that - takes the real object to set property on - - - - pointer to take the specification - describing the property - - - - - - Removes the #GstControlBinding that was created for the specified child -property of the track element using -ges_track_element_set_control_source(). The given @property_name must -be the same name of the child property that was passed to -ges_track_element_set_control_source(). - - - %TRUE if the control binding was removed from the specified -child property of @object, or %FALSE if an error occurred. - - - - - A #GESTrackElement - - - - The name of the child property to remove the control -binding from - - - - - - Sets #GESTrackElement:active for the element. - - - %TRUE if the property was *toggled*. - - - - - A #GESTrackElement - - - - Whether @object should be active in its track - - - - - - Sets #GESTrackElement:auto-clamp-control-sources. If set to %TRUE, this -will immediately clamp all the control sources. - - - - - - - A #GESTrackElement - - - - Whether to automatically clamp the control sources for the -child properties of @object - - - - - - Sets a property of a child of @object. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. - Use #ges_timeline_element_set_child_properties - - - - - - - The #GESTrackElement parent object - - - - The name of the first property to set - - - - value for the first property, followed optionally by more -name/return location pairs, followed by NULL - - - - - - Sets a property of a GstElement contained in @object. - -Note that #ges_track_element_set_child_property is really -intended for language bindings, #ges_track_element_set_child_properties -is much more convenient for C programming. - use #ges_timeline_element_set_child_property instead - - - %TRUE if the property was set, %FALSE otherwise. - - - - - The origin #GESTrackElement - - - - The name of the property - - - - The value - - - - - - Sets a property of a child of @object. - Use #ges_timeline_element_set_child_property_by_spec - - - - - - - A #GESTrackElement - - - - The #GParamSpec that specifies the property you want to set - - - - The value - - - - - - Sets a property of a child of @object. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. - Use #ges_timeline_element_set_child_property_valist - - - - - - - The #GESTrackElement parent object - - - - The name of the first property to set - - - - Value for the first property, followed optionally by more -name/return location pairs, followed by NULL - - - - - - Creates a #GstControlBinding for the specified child property of the -track element using the given control source. The given @property_name -should refer to an existing child property of the track element, as -used in ges_timeline_element_lookup_child(). - -If @binding_type is "direct", then the control binding is created with -gst_direct_control_binding_new() using the given control source. If -@binding_type is "direct-absolute", it is created with -gst_direct_control_binding_new_absolute() instead. - - - %TRUE if the specified child property could be bound to -@source, or %FALSE if an error occurred. - - - - - A #GESTrackElement - - - - The control source to bind the child property to - - - - The name of the child property to control - - - - The type of binding to create ("direct" or -"direct-absolute") - - - - - - Sets #GESTrackElement:has-internal-source for the element. If this is -set to %FALSE, this method will also set the -#GESTimelineElement:in-point of the element to 0 and its -#GESTimelineElement:max-duration to #GST_CLOCK_TIME_NONE. - - - %FALSE if @has_internal_source is forbidden for @object and -%TRUE in any other case. - - - - - A #GESTrackElement - - - - Whether the @object should be allowed to have its -'internal time' properties set. - - - - - - Sets the #GESTrackElement:track-type for the element. - - - - - - - A #GESTrackElement - - - - The new track-type for @object - - - - - - Whether the effect of the element should be applied in its -#GESTrackElement:track. If set to %FALSE, it will not be used in -the output of the track. - - - - Whether the control sources on the element (see -ges_track_element_set_control_source()) will be automatically -updated whenever the #GESTimelineElement:in-point or out-point of the -element change in value. - -See ges_track_element_clamp_control_source() for how this is done -per control source. - -Default value: %TRUE - - - - This property is used to determine whether the 'internal time' -properties of the element have any meaning. In particular, unless -this is set to %TRUE, the #GESTimelineElement:in-point and -#GESTimelineElement:max-duration can not be set to any value other -than the default 0 and #GST_CLOCK_TIME_NONE, respectively. - -If an element has some *internal* *timed* source #GstElement that it -reads stream data from as part of its function in a #GESTrack, then -you'll likely want to set this to %TRUE to allow the -#GESTimelineElement:in-point and #GESTimelineElement:max-duration to -be set. - -The default value is determined by the #GESTrackElementClass -@default_has_internal_source class property. For most -#GESSourceClass-es, this will be %TRUE, with the exception of those -that have a potentially *static* source, such as #GESImageSourceClass -and #GESTitleSourceClass. Otherwise, this will usually be %FALSE. - -For most #GESOperation-s you will likely want to leave this set to -%FALSE. The exception may be for an operation that reads some stream -data from some private internal source as part of manipulating the -input data from the usual linked upstream #GESTrackElement. - -For example, you may want to set this to %TRUE for a -#GES_TRACK_TYPE_VIDEO operation that wraps a #textoverlay that reads -from a subtitle file and places its text on top of the received video -data. The #GESTimelineElement:in-point of the element would be used -to shift the initial seek time on the #textoverlay away from 0, and -the #GESTimelineElement:max-duration could be set to reflect the -time at which the subtitle file runs out of data. - -Note that GES can not support track elements that have both internal -content and manipulate the timing of their data streams (time -effects). - - - - The track that this element belongs to, or %NULL if it does not -belong to a track. - - - - The track type of the element, which determines the type of track the -element can be added to (see #GESTrack:track-type). This should -correspond to the type of data that the element can produce or -process. - - - - - - - - - - - - - - - - - - - - - This is emitted when a control binding is added to a child property -of the track element. - - - - - - The control binding that has been added - - - - - - This is emitted when a control binding is removed from a child -property of the track element. - - - - - - The control binding that has been removed - - - - - - - - - - - - Result: %TRUE if @self has a natural framerate %FALSE otherwise - - - %TRUE if @self has a natural framerate @FALSE otherwise. - - - - - A #GESAsset - - - - The framerate numerator - - - - The framerate denominator - - - - - - Result: %TRUE if @self has a natural framerate %FALSE otherwise - - - - - - - A #GESAsset - - - - The framerate numerator - - - - The framerate denominator - - - - - - Get the GESAssetTrackType the #GESTrackElement extracted from @self -should get into - - - a #GESTrackType - - - - - A #GESAsset - - - - - - Set the #GESTrackType the #GESTrackElement extracted from @self -should get into - - - - - - - A #GESAsset - - - - A #GESTrackType - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if @self has a natural framerate @FALSE otherwise. - - - - - A #GESAsset - - - - The framerate numerator - - - - The framerate denominator - - - - - - - - - - - - - - - - - - - - - The name of the #GstElementFactory to use to -create the underlying nleobject of a track element - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TRUE if @element and @pspec could be found. FALSE otherwise. In that -case the values for @pspec and @element are not modified. Unref @element after -usage. - - - - - Object to lookup the property in - - - - Name of the property to look up. You can specify the name of the - class as such: "ClassName::property-name", to guarantee that you get the - proper GParamSpec in case various GstElement-s contain the same property - name. If you don't do so, you will get the first element found, having - this property and the and the corresponding GParamSpec. - - - - pointer to a #GstElement that - takes the real object to set property on - - - - pointer to take the specification - describing the property - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Types of content handled by a track. If the content is not one of -@GES_TRACK_TYPE_AUDIO, @GES_TRACK_TYPE_VIDEO or @GES_TRACK_TYPE_TEXT, -the user of the #GESTrack must set the type to @GES_TRACK_TYPE_CUSTOM. - -@GES_TRACK_TYPE_UNKNOWN is for internal purposes and should not be used -by users - - A track of unknown type (i.e. invalid) - - - An audio track - - - A video track - - - A text (subtitle) track - - - A custom-content track - - - - - - - - - - - - - - - Base class for media transitions. - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates an object that mixes together the two underlying objects, A and B. -The A object is assumed to have a higher prioirity (lower number) than the -B object. At the transition in point, only A will be visible, and by the -end only B will be visible. - -The shape of the video transition depends on the value of the "vtype" -property. The default value is "crossfade". For audio, only "crossfade" is -supported. - -The ID of the ExtractableType is the nickname of the vtype property value. Note -that this value can be changed after creation and the GESExtractable.asset value -will be updated when needed. - - - - - Creates a new #GESTransitionClip. - - - a newly created #GESTransitionClip, -or %NULL if something went wrong. - - - - - the type of transition to create - - - - - - Creates a new #GESTransitionClip for the provided @nick. - - - The newly created #GESTransitionClip, -or %NULL if something went wrong - - - - - a string representing the type of transition to create - - - - - - a #GESVideoStandardTransitionType representing the wipe to use - - - - - - - a #GESVideoStandardTransitionType indicating the type of video transition -to apply. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Represents all the output streams from a particular uri. It is assumed that -the URI points to a file of some type. - - - - - Creates a new #GESUriClip for the provided @uri. - -> **WARNING**: This function might 'discover` @uri **synchrounously**, it is -> an IO and processing intensive task that you probably don't want to run in -> an application mainloop. Have a look at #ges_asset_request_async to see how -> to make that operation happen **asynchronously**. - - - The newly created #GESUriClip, or -%NULL if there was an error. - - - - - the URI the source should control - - - - - - Get the location of the resource. - - - The location of the resource. - - - - - the #GESUriClip - - - - - - Lets you know if @self is an image or not. - - - %TRUE if @self is a still image %FALSE otherwise. - - - - - the #GESUriClip - - - - - - Lets you know if the audio track of @self is muted or not. - - - %TRUE if the audio track of @self is muted, %FALSE otherwise. - - - - - the #GESUriClip - - - - - - Sets whether the clip is a still image or not. - - - - - - - the #GESUriClip - - - - %TRUE if @self is a still image, %FALSE otherwise - - - - - - Sets whether the audio track of this clip is muted or not. - - - - - - - the #GESUriClip on which to mute or unmute the audio track - - - - %TRUE to mute @self audio track, %FALSE to unmute it - - - - - - Whether this uri clip represents a still image or not. This must be set -before create_track_elements is called. - - - - Whether the sound will be played or not. - - - - - - - The location of the file/resource to use. - - - - - - - - - - - - - - - - - - - - - Finalize the request of an async #GESUriClipAsset - - - The #GESUriClipAsset previously requested - - - - - The #GAsyncResult from which to get the newly created #GESUriClipAsset - - - - - - Creates a #GESUriClipAsset for @uri - -Example of request of a GESUriClipAsset: -|[ -// The request callback -static void -filesource_asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data) -{ - GError *error = NULL; - GESUriClipAsset *filesource_asset; - - filesource_asset = ges_uri_clip_asset_finish (res, &error); - if (filesource_asset) { - g_print ("The file: %s is usable as a FileSource, it is%s an image and lasts %" GST_TIME_FORMAT, - ges_asset_get_id (GES_ASSET (filesource_asset)) - ges_uri_clip_asset_is_image (filesource_asset) ? "" : " not", - GST_TIME_ARGS (ges_uri_clip_asset_get_duration (filesource_asset)); - } else { - g_print ("The file: %s is *not* usable as a FileSource because: %s", - ges_asset_get_id (source), error->message); - } - - gst_object_unref (mfs); -} - -// The request: -ges_uri_clip_asset_new (uri, (GAsyncReadyCallback) filesource_asset_loaded_cb, user_data); -]| - - - - - - - The URI of the file for which to create a #GESUriClipAsset - - - - optional %GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the initialization is finished - - - - The user data to pass when @callback is called - - - - - - Creates a #GESUriClipAsset for @uri syncronously. You should avoid -to use it in application, and rather create #GESUriClipAsset asynchronously - - - A reference to the requested asset or %NULL if -an error happened - - - - - The URI of the file for which to create a #GESUriClipAsset. -You can also use multi file uris for #GESMultiFileSource. - - - - - - Gets duration of the file represented by @self - - - The duration of @self - - - - - a #GESUriClipAsset - - - - - - Gets #GstDiscovererInfo about the file - - - #GstDiscovererInfo of specified asset - - - - - Target asset - - - - - - Gets maximum duration of the file represented by @self, -it is usually the same as GESUriClipAsset::duration, -but in the case of nested timelines, for example, they -are different as those can be extended 'infinitely'. - - - The maximum duration of @self - - - - - a #GESUriClipAsset - - - - - - Get the GESUriSourceAsset @self containes - - - a -#GList of #GESUriSourceAsset - - - - - - - A #GESUriClipAsset - - - - - - Gets Whether the file represented by @self is an image or not - - - Whether the file represented by @self is an image or not - - - - - a #GESUriClipAsset - - - - - - The duration (in nanoseconds) of the media file - - - - The duration (in nanoseconds) of the media file - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Sets the timeout of #GESUriClipAsset loading - - - - - - - The #GESUriClipAssetClass on which to set the discoverer timeout - - - - The timeout to set - - - - - - - - - - - - - - - - - - - - - - - - - - - - Asset to create a stream specific #GESSource for a media file. - -NOTE: You should never request such a #GESAsset as they will be created automatically -by #GESUriClipAsset-s. - - - - - - Get the #GESUriClipAsset @self is contained in - - - a #GESUriClipAsset - - - - - A #GESUriClipAsset - - - - - - Get the #GstDiscovererStreamInfo user by @asset - - - a #GESUriClipAsset - - - - - A #GESUriClipAsset - - - - - - - - - - - - - - - - - Check if @asset contains a single image - - - %TRUE if the video stream corresponds to an image (i.e. only -contains one frame) - - - - - A #GESUriClipAsset - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for video sources - - - - - Retrieves the natural size of the video stream. The natural size, is -the size at which it will be displayed if no scaling is being applied. - -NOTE: The sources take into account the potential video rotation applied -by the #videoflip element that is inside the source, effects applied on -the clip which potentially also rotate the element are not taken into -account. - - - %TRUE if the object has a natural size, %FALSE otherwise. - - - - - A #GESVideoSource - - - - The natural width of the underlying source - - - - The natural height of the underlying source - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Transition type has not been set, - - - A bar moves from left to right, - - - A bar moves from top to bottom, - - - A box expands from the upper-left corner to the lower-right corner, - - - A box expands from the upper-right corner to the lower-left corner, - - - A box expands from the lower-right corner to the upper-left corner, - - - A box expands from the lower-left corner to the upper-right corner, - - - A box shape expands from each of the four corners toward the center, - - - A box shape expands from the center of each quadrant toward the corners of each quadrant, - - - A central, vertical line splits and expands toward the left and right edges, - - - A central, horizontal line splits and expands toward the top and bottom edges, - - - A box expands from the top edge's midpoint to the bottom corners, - - - A box expands from the right edge's midpoint to the left corners, - - - A box expands from the bottom edge's midpoint to the top corners, - - - A box expands from the left edge's midpoint to the right corners, - - - A diagonal line moves from the upper-left corner to the lower-right corner, - - - A diagonal line moves from the upper right corner to the lower-left corner, - - - Two wedge shapes slide in from the top and bottom edges toward the center, - - - Two wedge shapes slide in from the left and right edges toward the center, - - - A diagonal line from the lower-left to upper-right corners splits and expands toward the opposite corners, - - - A diagonal line from upper-left to lower-right corners splits and expands toward the opposite corners, - - - Four wedge shapes split from the center and retract toward the four edges, - - - A diamond connecting the four edge midpoints simultaneously contracts toward the center and expands toward the edges, - - - A wedge shape moves from top to bottom, - - - A wedge shape moves from right to left, - - - A wedge shape moves from bottom to top, - - - A wedge shape moves from left to right, - - - A 'V' shape extending from the bottom edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - - - A 'V' shape extending from the left edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - - - A 'V' shape extending from the top edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - - - A 'V' shape extending from the right edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - - - A rectangle expands from the center., - - - A radial hand sweeps clockwise from the twelve o'clock position, - - - A radial hand sweeps clockwise from the three o'clock position, - - - A radial hand sweeps clockwise from the six o'clock position, - - - A radial hand sweeps clockwise from the nine o'clock position, - - - Two radial hands sweep clockwise from the twelve and six o'clock positions, - - - Two radial hands sweep clockwise from the nine and three o'clock positions, - - - Four radial hands sweep clockwise, - - - A fan unfolds from the top edge, the fan axis at the center, - - - A fan unfolds from the right edge, the fan axis at the center, - - - Two fans, their axes at the center, unfold from the top and bottom, - - - Two fans, their axes at the center, unfold from the left and right, - - - A radial hand sweeps clockwise from the top edge's midpoint, - - - A radial hand sweeps clockwise from the right edge's midpoint, - - - A radial hand sweeps clockwise from the bottom edge's midpoint, - - - A radial hand sweeps clockwise from the left edge's midpoint, - - - Two radial hands sweep clockwise and counter-clockwise from the top and bottom edges' midpoints, - - - Two radial hands sweep clockwise and counter-clockwise from the left and right edges' midpoints, - - - Two radial hands attached at the top and bottom edges' midpoints sweep from right to left, - - - Two radial hands attached at the left and right edges' midpoints sweep from top to bottom, - - - A fan unfolds from the bottom, the fan axis at the top edge's midpoint, - - - A fan unfolds from the left, the fan axis at the right edge's midpoint, - - - A fan unfolds from the top, the fan axis at the bottom edge's midpoint, - - - A fan unfolds from the right, the fan axis at the left edge's midpoint, - - - Two fans, their axes at the top and bottom, unfold from the center, - - - Two fans, their axes at the left and right, unfold from the center, - - - A radial hand sweeps clockwise from the upper-left corner, - - - A radial hand sweeps counter-clockwise from the lower-left corner., - - - A radial hand sweeps clockwise from the lower-right corner, - - - A radial hand sweeps counter-clockwise from the upper-right corner, - - - Two radial hands attached at the upper-left and lower-right corners sweep down and up, - - - Two radial hands attached at the lower-left and upper-right corners sweep down and up, - - - Two radial hands attached at the upper-left and upper-right corners sweep down, - - - Two radial hands attached at the upper-left and lower-left corners sweep to the right, - - - Two radial hands attached at the lower-left and lower-right corners sweep up, - - - Two radial hands attached at the upper-right and lower-right corners sweep to the left, - - - Two radial hands attached at the midpoints of the top and bottom halves sweep from right to left, - - - Two radial hands attached at the midpoints of the left and right halves sweep from top to bottom, - - - Two sets of radial hands attached at the midpoints of the top and bottom halves sweep from top to bottom and bottom to top, - - - Two sets of radial hands attached at the midpoints of the left and right halves sweep from left to right and right to left, - - - Crossfade - - - - The test pattern to produce - - A standard SMPTE test pattern - - - Random noise - - - A black image - - - A white image - - - A red image - - - A green image - - - A blue image - - - Checkers pattern (1px) - - - Checkers pattern (2px) - - - Checkers pattern (4px) - - - Checkers pattern (8px) - - - Circular pattern - - - Alternate between black and white - - - SMPTE test pattern (75% color bars) - - - Zone plate - - - Gamut checkers - - - Chroma zone plate - - - Solid color - - - - ### Children Properties - - {{ libs/GESVideoTestSource-children-props.md }} - - - - - Get the video pattern used by the @source. - - - The video pattern used by the @source. - - - - - a #GESVideoTestPattern - - - - - - Sets the source to use the given @pattern. - - - - - - - a #GESVideoTestSource - - - - a #GESVideoTestPattern - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GESVideoTrack is a default video #GESTrack, with a -#GES_TRACK_TYPE_VIDEO #GESTrack:track-type and "video/x-raw(ANY)" -#GESTrack:caps. - -By default, a video track will have its #GESTrack:restriction-caps -set to "video/x-raw" with the following properties: - -- width: 1280 -- height: 720 -- framerate: 30/1 - -These fields are needed for negotiation purposes, but you can change -their values if you wish. It is advised that you do so using -ges_track_update_restriction_caps() with new values for the fields you -wish to change, and any additional fields you may want to add. Unlike -using ges_track_set_restriction_caps(), this will ensure that these -default fields will at least have some value set. - - - - - Creates a new video track, with a #GES_TRACK_TYPE_VIDEO -#GESTrack:track-type and "video/x-raw(ANY)" #GESTrack:caps, and -"video/x-raw" #GESTrack:restriction-caps with the properties: - -- width: 1280 -- height: 720 -- framerate: 30/1 - -You should use ges_track_update_restriction_caps() if you wish to -modify these fields, or add additional ones. - - - The newly created video track. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the border property of @self, this value represents -the border width of the transition. - - - The border values of @self or -1 if not meaningful -(this will happen when not using a smpte transition). - - - - - The #GESVideoTransition to get the border from - - - - - - Get the transition type used by @trans. - - - The transition type used by @trans. - - - - - a #GESVideoTransition - - - - - - Get the invert property of @self, this value represents -the direction of the transition. - - - The invert value of @self - - - - - The #GESVideoTransition to get the inversion from - - - - - - Set the border property of @self, this value represents -the border width of the transition. In case this value does -not make sense for the current transition type, it is cached -for later use. - - - - - - - The #GESVideoTransition to set the border to - - - - The value of the border to set on @object - - - - - - Set the invert property of @self, this value represents -the direction of the transition. In case this value does -not make sense for the current transition type, it is cached -for later use. - - - - - - - The #GESVideoTransition to set invert on - - - - %TRUE if the transition should be inverted %FALSE otherwise - - - - - - Sets the transition being used to @type. - - - %TRUE if the transition type was properly changed, else %FALSE. - - - - - a #GESVideoTransition - - - - a #GESVideoStandardTransitionType - - - - - - This value represents the border width of the transition. - - - - This value represents the direction of the transition. - - - - - - - - - - - - - - - - - - - - - parent class - - - - - - - - - - - - - ### Children Properties - - {{ libs/GESVideoUriSource-children-props.md }} - - - - - The location of the file/resource to use. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Clean up any resources created by GES in ges_init(). - -It is normally not needed to call this function in a normal application as the -resources will automatically be freed when the program terminates. -This function is therefore mostly used by testsuites and other memory profiling tools. -This function should be called from the thread where ges_init() was called. - -After this call GES should not be used until another ges_init() call. - - - - - - - - - A human friendly name for @edge - - - - - The #GESEdge to get the name of - - - - - - Return a string representation of @mode. - - - a string representation of @mode. - - - - - a #GESEditMode - - - - - - Get the best formatter for @uri. It tries to find a formatter -compatible with @uri extension, if none is found, it returns the default -formatter asset. - - - The #GESAsset for the best formatter to save to @uri - - - - - - - - - - Initialize the GStreamer Editing Service. Call this before any usage of -GES. You should take care of initilizing GStreamer before calling this -function. - -MT safety. -GStreamer Editing Services do not guarantee MT safety. -An application is required to use GES APIs (including ges_deinit()) -in the thread where ges_init() was called. - - - - - - - Initializes the GStreamer Editing Services library, setting up internal path lists, -and loading evrything needed. - -This function will return %FALSE if GES could not be initialized -for some reason. - - - %TRUE if GES could be initialized. - - - - - pointer to application's argc - - - - pointer to application's argv - - - - - - - - Returns a #GOptionGroup with GES's argument specifications. The -group is set up to use standard GOption callbacks, so when using this -group in combination with GOption parsing methods, all argument parsing -and initialization is automated. - -This function is useful if you want to integrate GES with other -libraries that use GOption (see g_option_context_add_group() ). - -If you use this function, you should make sure you initialise the GStreamer -as one of the very first things in your program. That means you need to -use gst_init_get_option_group() and add it to the option context before -using the ges_init_get_option_group() result. - - - a pointer to GES's option group. - - - - - Use this function to check if GES has been initialized with ges_init() -or ges_init_check(). - - - %TRUE if initialization has been done, %FALSE otherwise. - - - - - List all the assets in the current cache whose -#GESAsset:extractable-type are of the given type (including -subclasses). - -Note that, since only a #GESExtractable can be extracted from an asset, -using `GES_TYPE_EXTRACTABLE` as @filter will return all the assets in -the current cache. - - - A list of all -#GESAsset-s currently in the cache whose #GESAsset:extractable-type is -of the @filter type. - - - - - - - The type of object that can be extracted from the asset - - - - - - Get the last buffer @playsink showed - Use the "convert-sample" action signal of -#playsink instead. - - - A #GstSample containing the last frame from -@playsink in the format defined by the @caps - - - - - The playsink to get last frame from - - - - The caps defining the format the return value will have - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Helper macro to retrieve the project from which @obj was extracted - - - - The #GESTimeline from which to retrieve the project - - - - - - - - - - - - - - - - - - - - - - Gets the version number of the GStreamer Editing Services library. - - - - - - - pointer to a guint to store the major version number - - - - pointer to a guint to store the minor version number - - - - pointer to a guint to store the micro version number - - - - pointer to a guint to store the nano version number - - - - - - diff --git a/gir-files/GLib-2.0.gir b/gir-files/GLib-2.0.gir deleted file mode 100644 index a5a98f4cc..000000000 --- a/gir-files/GLib-2.0.gir +++ /dev/null @@ -1,51822 +0,0 @@ - - - - - - - - Integer representing a day of the month; between 1 and 31. -#G_DATE_BAD_DAY represents an invalid day of the month. - - - - - Integer representing a year; #G_DATE_BAD_YEAR is the invalid -value. The year must be 1 or higher; negative (BC) years are not -allowed. The year is represented with four digits. - - - - - Opaque type. See g_main_context_pusher_new() for details. - - - - - Opaque type. See g_mutex_locker_new() for details. - - - - - A type which is used to hold a process identification. - -On UNIX, processes are identified by a process id (an integer), -while Windows uses process handles (which are pointers). - -GPid is used in GLib only for descendant processes spawned with -the g_spawn functions. - - - - - A GQuark is a non-zero integer which uniquely identifies a -particular string. A GQuark value of zero is associated to %NULL. - - - - - Opaque type. See g_rw_lock_reader_locker_new() for details. - - - - - Opaque type. See g_rw_lock_writer_locker_new() for details. - - - - - Opaque type. See g_rec_mutex_locker_new() for details. - - - - - A typedef for a reference-counted string. A pointer to a #GRefString can be -treated like a standard `char*` array by all code, but can additionally have -`g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be -called on `char*` arrays not allocated using g_ref_string_new(). - -If using #GRefString with autocleanups, g_autoptr() must be used rather than -g_autofree(), so that the reference counting metadata is also freed. - - - - - A typedef alias for gchar**. This is mostly useful when used together with -g_auto(). - - - - - Simply a replacement for `time_t`. It has been deprecated -since it is not equivalent to `time_t` on 64-bit platforms -with a 64-bit `time_t`. Unrelated to #GTimer. - -Note that #GTime is defined to always be a 32-bit integer, -unlike `time_t` which may be 64-bit on some systems. Therefore, -#GTime will overflow in the year 2038, and you cannot use the -address of a #GTime variable as argument to the UNIX time() -function. - -Instead, do the following: -|[<!-- language="C" --> -time_t ttime; -GTime gtime; - -time (&ttime); -gtime = (GTime)ttime; -]| - This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem). - Use #GDateTime or #time_t instead. - - - - - A value representing an interval of time, in microseconds. - - - - - - - - - Return the minimal alignment required by the platform ABI for values of the given -type. The address of a variable or struct member of the given type must always be -a multiple of this alignment. For example, most platforms require int variables -to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. - -Note this is not necessarily the same as the value returned by GCC’s -`__alignof__` operator, which returns the preferred alignment for a type. -The preferred alignment may be a stricter alignment than the minimal -alignment. - - - - a type-name - - - - - - - - - Evaluates to a truth value if the absolute difference between @a and @b is -smaller than @epsilon, and to a false value otherwise. - -For example, -- `G_APPROX_VALUE (5, 6, 2)` evaluates to true -- `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false -- `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within - the single precision floating point epsilon from zero - - - - a numeric value - - - a numeric value - - - a numeric value that expresses the tolerance between @a and @b - - - - - A good size for a buffer to be passed into g_ascii_dtostr(). -It is guaranteed to be enough for all output of that function -on systems with 64bit IEEE-compatible doubles. - -The typical usage would be something like: -|[<!-- language="C" --> - char buf[G_ASCII_DTOSTR_BUF_SIZE]; - - fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); -]| - - - - - - - - - - - - Contains the public fields of a GArray. - - - a pointer to the element data. The data may be moved as - elements are added to the #GArray. - - - - the number of elements in the #GArray not including the - possible terminating zero element. - - - - Adds @len elements onto the end of the array. - - - the #GArray - - - - - - - a #GArray - - - - - - a pointer to the elements to append to the end of the array - - - - the number of elements to append - - - - - - Checks whether @target exists in @array by performing a binary -search based on the given comparison function @compare_func which -get pointers to items as arguments. If the element is found, %TRUE -is returned and the element’s index is returned in @out_match_index -(if non-%NULL). Otherwise, %FALSE is returned and @out_match_index -is undefined. If @target exists multiple times in @array, the index -of the first instance is returned. This search is using a binary -search, so the @array must absolutely be sorted to return a correct -result (if not, the function may produce false-negative). - -This example defines a comparison function and search an element in a #GArray: -|[<!-- language="C" --> -static gint* -cmpint (gconstpointer a, gconstpointer b) -{ - const gint *_a = a; - const gint *_b = b; - - return *_a - *_b; -} -... -gint i = 424242; -guint matched_index; -gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index); -... -]| - - - %TRUE if @target is one of the elements of @array, %FALSE otherwise. - - - - - a #GArray. - - - - - - a pointer to the item to look up. - - - - A #GCompareFunc used to locate @target. - - - - return location - for the index of the element, if found. - - - - - - Create a shallow copy of a #GArray. If the array elements consist of -pointers to data, the pointers are copied but the actual data is not. - - - A copy of @array. - - - - - - - A #GArray. - - - - - - - - Frees the memory allocated for the #GArray. If @free_segment is -%TRUE it frees the memory block holding the elements as well. Pass -%FALSE if you want to free the #GArray wrapper but preserve the -underlying array for use elsewhere. If the reference count of -@array is greater than one, the #GArray wrapper is preserved but -the size of @array will be set to zero. - -If array contents point to dynamically-allocated memory, they should -be freed separately if @free_seg is %TRUE and no @clear_func -function has been set for @array. - -This function is not thread-safe. If using a #GArray from multiple -threads, use only the atomic g_array_ref() and g_array_unref() -functions. - - - the element data if @free_segment is %FALSE, otherwise - %NULL. The element data should be freed using g_free(). - - - - - a #GArray - - - - - - if %TRUE the actual element data is freed as well - - - - - - Gets the size of the elements in @array. - - - Size of each element, in bytes - - - - - A #GArray - - - - - - - - Inserts @len elements into a #GArray at the given index. - -If @index_ is greater than the array’s current length, the array is expanded. -The elements between the old end of the array and the newly inserted elements -will be initialised to zero if the array was configured to clear elements; -otherwise their values will be undefined. - -@data may be %NULL if (and only if) @len is zero. If @len is zero, this -function is a no-op. - - - the #GArray - - - - - - - a #GArray - - - - - - the index to place the elements at - - - - a pointer to the elements to insert - - - - the number of elements to insert - - - - - - Creates a new #GArray with a reference count of 1. - - - the new #GArray - - - - - - - %TRUE if the array should have an extra element at - the end which is set to 0 - - - - %TRUE if #GArray elements should be automatically cleared - to 0 when they are allocated - - - - the size of each element in bytes - - - - - - Adds @len elements onto the start of the array. - -@data may be %NULL if (and only if) @len is zero. If @len is zero, this -function is a no-op. - -This operation is slower than g_array_append_vals() since the -existing elements in the array have to be moved to make space for -the new elements. - - - the #GArray - - - - - - - a #GArray - - - - - - a pointer to the elements to prepend to the start of the array - - - - the number of elements to prepend, which may be zero - - - - - - Atomically increments the reference count of @array by one. -This function is thread-safe and may be called from any thread. - - - The passed in #GArray - - - - - - - A #GArray - - - - - - - - Removes the element at the given index from a #GArray. The following -elements are moved down one place. - - - the #GArray - - - - - - - a #GArray - - - - - - the index of the element to remove - - - - - - Removes the element at the given index from a #GArray. The last -element in the array is used to fill in the space, so this function -does not preserve the order of the #GArray. But it is faster than -g_array_remove_index(). - - - the #GArray - - - - - - - a @GArray - - - - - - the index of the element to remove - - - - - - Removes the given number of elements starting at the given index -from a #GArray. The following elements are moved to close the gap. - - - the #GArray - - - - - - - a @GArray - - - - - - the index of the first element to remove - - - - the number of elements to remove - - - - - - Sets a function to clear an element of @array. - -The @clear_func will be called when an element in the array -data segment is removed and when the array is freed and data -segment is deallocated as well. @clear_func will be passed a -pointer to the element to clear, rather than the element itself. - -Note that in contrast with other uses of #GDestroyNotify -functions, @clear_func is expected to clear the contents of -the array element it is given, but not free the element itself. - - - - - - - A #GArray - - - - - - a function to clear an element of @array - - - - - - Sets the size of the array, expanding it if necessary. If the array -was created with @clear_ set to %TRUE, the new elements are set to 0. - - - the #GArray - - - - - - - a #GArray - - - - - - the new size of the #GArray - - - - - - Creates a new #GArray with @reserved_size elements preallocated and -a reference count of 1. This avoids frequent reallocation, if you -are going to add many elements to the array. Note however that the -size of the array is still 0. - - - the new #GArray - - - - - - - %TRUE if the array should have an extra element at - the end with all bits cleared - - - - %TRUE if all bits in the array should be cleared to 0 on - allocation - - - - size of each element in the array - - - - number of elements preallocated - - - - - - Sorts a #GArray using @compare_func which should be a qsort()-style -comparison function (returns less than zero for first arg is less -than second arg, zero for equal, greater zero if first arg is -greater than second arg). - -This is guaranteed to be a stable sort since version 2.32. - - - - - - - a #GArray - - - - - - comparison function - - - - - - Like g_array_sort(), but the comparison function receives an extra -user data argument. - -This is guaranteed to be a stable sort since version 2.32. - -There used to be a comment here about making the sort stable by -using the addresses of the elements in the comparison function. -This did not actually work, so any such code should be removed. - - - - - - - a #GArray - - - - - - comparison function - - - - data to pass to @compare_func - - - - - - Frees the data in the array and resets the size to zero, while -the underlying array is preserved for use elsewhere and returned -to the caller. - -If the array was created with the @zero_terminate property -set to %TRUE, the returned data is zero terminated too. - -If array elements contain dynamically-allocated memory, -the array elements should also be freed by the caller. - -A short example of use: -|[<!-- language="C" --> -... -gpointer data; -gsize data_len; -data = g_array_steal (some_array, &data_len); -... -]| - - - the element data, which should be - freed using g_free(). - - - - - a #GArray. - - - - - - pointer to retrieve the number of - elements of the original array - - - - - - Atomically decrements the reference count of @array by one. If the -reference count drops to 0, all memory allocated by the array is -released. This function is thread-safe and may be called from any -thread. - - - - - - - A #GArray - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The GAsyncQueue struct is an opaque data structure which represents -an asynchronous queue. It should only be accessed through the -g_async_queue_* functions. - - - Returns the length of the queue. - -Actually this function returns the number of data items in -the queue minus the number of waiting threads, so a negative -value means waiting threads, and a positive value means available -entries in the @queue. A return value of 0 could mean n entries -in the queue and n threads waiting. This can happen due to locking -of the queue or due to scheduling. - - - the length of the @queue - - - - - a #GAsyncQueue. - - - - - - Returns the length of the queue. - -Actually this function returns the number of data items in -the queue minus the number of waiting threads, so a negative -value means waiting threads, and a positive value means available -entries in the @queue. A return value of 0 could mean n entries -in the queue and n threads waiting. This can happen due to locking -of the queue or due to scheduling. - -This function must be called while holding the @queue's lock. - - - the length of the @queue. - - - - - a #GAsyncQueue - - - - - - Acquires the @queue's lock. If another thread is already -holding the lock, this call will block until the lock -becomes available. - -Call g_async_queue_unlock() to drop the lock again. - -While holding the lock, you can only call the -g_async_queue_*_unlocked() functions on @queue. Otherwise, -deadlock may occur. - - - - - - - a #GAsyncQueue - - - - - - Pops data from the @queue. If @queue is empty, this function -blocks until data becomes available. - - - data from the queue - - - - - a #GAsyncQueue - - - - - - Pops data from the @queue. If @queue is empty, this function -blocks until data becomes available. - -This function must be called while holding the @queue's lock. - - - data from the queue. - - - - - a #GAsyncQueue - - - - - - Pushes the @data into the @queue. @data must not be %NULL. - - - - - - - a #GAsyncQueue - - - - @data to push into the @queue - - - - - - Pushes the @item into the @queue. @item must not be %NULL. -In contrast to g_async_queue_push(), this function -pushes the new item ahead of the items already in the queue, -so that it will be the next one to be popped off the queue. - - - - - - - a #GAsyncQueue - - - - data to push into the @queue - - - - - - Pushes the @item into the @queue. @item must not be %NULL. -In contrast to g_async_queue_push_unlocked(), this function -pushes the new item ahead of the items already in the queue, -so that it will be the next one to be popped off the queue. - -This function must be called while holding the @queue's lock. - - - - - - - a #GAsyncQueue - - - - data to push into the @queue - - - - - - Inserts @data into @queue using @func to determine the new -position. - -This function requires that the @queue is sorted before pushing on -new elements, see g_async_queue_sort(). - -This function will lock @queue before it sorts the queue and unlock -it when it is finished. - -For an example of @func see g_async_queue_sort(). - - - - - - - a #GAsyncQueue - - - - the @data to push into the @queue - - - - the #GCompareDataFunc is used to sort @queue - - - - user data passed to @func. - - - - - - Inserts @data into @queue using @func to determine the new -position. - -The sort function @func is passed two elements of the @queue. -It should return 0 if they are equal, a negative value if the -first element should be higher in the @queue or a positive value -if the first element should be lower in the @queue than the second -element. - -This function requires that the @queue is sorted before pushing on -new elements, see g_async_queue_sort(). - -This function must be called while holding the @queue's lock. - -For an example of @func see g_async_queue_sort(). - - - - - - - a #GAsyncQueue - - - - the @data to push into the @queue - - - - the #GCompareDataFunc is used to sort @queue - - - - user data passed to @func. - - - - - - Pushes the @data into the @queue. @data must not be %NULL. - -This function must be called while holding the @queue's lock. - - - - - - - a #GAsyncQueue - - - - @data to push into the @queue - - - - - - Increases the reference count of the asynchronous @queue by 1. -You do not need to hold the lock to call this function. - - - the @queue that was passed in (since 2.6) - - - - - a #GAsyncQueue - - - - - - Increases the reference count of the asynchronous @queue by 1. - Reference counting is done atomically. -so g_async_queue_ref() can be used regardless of the @queue's -lock. - - - - - - - a #GAsyncQueue - - - - - - Remove an item from the queue. - - - %TRUE if the item was removed - - - - - a #GAsyncQueue - - - - the data to remove from the @queue - - - - - - Remove an item from the queue. - -This function must be called while holding the @queue's lock. - - - %TRUE if the item was removed - - - - - a #GAsyncQueue - - - - the data to remove from the @queue - - - - - - Sorts @queue using @func. - -The sort function @func is passed two elements of the @queue. -It should return 0 if they are equal, a negative value if the -first element should be higher in the @queue or a positive value -if the first element should be lower in the @queue than the second -element. - -This function will lock @queue before it sorts the queue and unlock -it when it is finished. - -If you were sorting a list of priority numbers to make sure the -lowest priority would be at the top of the queue, you could use: -|[<!-- language="C" --> - gint32 id1; - gint32 id2; - - id1 = GPOINTER_TO_INT (element1); - id2 = GPOINTER_TO_INT (element2); - - return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); -]| - - - - - - - a #GAsyncQueue - - - - the #GCompareDataFunc is used to sort @queue - - - - user data passed to @func - - - - - - Sorts @queue using @func. - -The sort function @func is passed two elements of the @queue. -It should return 0 if they are equal, a negative value if the -first element should be higher in the @queue or a positive value -if the first element should be lower in the @queue than the second -element. - -This function must be called while holding the @queue's lock. - - - - - - - a #GAsyncQueue - - - - the #GCompareDataFunc is used to sort @queue - - - - user data passed to @func - - - - - - Pops data from the @queue. If the queue is empty, blocks until -@end_time or until data becomes available. - -If no data is received before @end_time, %NULL is returned. - -To easily calculate @end_time, a combination of g_get_real_time() -and g_time_val_add() can be used. - use g_async_queue_timeout_pop(). - - - data from the queue or %NULL, when no data is - received before @end_time. - - - - - a #GAsyncQueue - - - - a #GTimeVal, determining the final time - - - - - - Pops data from the @queue. If the queue is empty, blocks until -@end_time or until data becomes available. - -If no data is received before @end_time, %NULL is returned. - -To easily calculate @end_time, a combination of g_get_real_time() -and g_time_val_add() can be used. - -This function must be called while holding the @queue's lock. - use g_async_queue_timeout_pop_unlocked(). - - - data from the queue or %NULL, when no data is - received before @end_time. - - - - - a #GAsyncQueue - - - - a #GTimeVal, determining the final time - - - - - - Pops data from the @queue. If the queue is empty, blocks for -@timeout microseconds, or until data becomes available. - -If no data is received before the timeout, %NULL is returned. - - - data from the queue or %NULL, when no data is - received before the timeout. - - - - - a #GAsyncQueue - - - - the number of microseconds to wait - - - - - - Pops data from the @queue. If the queue is empty, blocks for -@timeout microseconds, or until data becomes available. - -If no data is received before the timeout, %NULL is returned. - -This function must be called while holding the @queue's lock. - - - data from the queue or %NULL, when no data is - received before the timeout. - - - - - a #GAsyncQueue - - - - the number of microseconds to wait - - - - - - Tries to pop data from the @queue. If no data is available, -%NULL is returned. - - - data from the queue or %NULL, when no data is - available immediately. - - - - - a #GAsyncQueue - - - - - - Tries to pop data from the @queue. If no data is available, -%NULL is returned. - -This function must be called while holding the @queue's lock. - - - data from the queue or %NULL, when no data is - available immediately. - - - - - a #GAsyncQueue - - - - - - Releases the queue's lock. - -Calling this function when you have not acquired -the with g_async_queue_lock() leads to undefined -behaviour. - - - - - - - a #GAsyncQueue - - - - - - Decreases the reference count of the asynchronous @queue by 1. - -If the reference count went to 0, the @queue will be destroyed -and the memory allocated will be freed. So you are not allowed -to use the @queue afterwards, as it might have disappeared. -You do not need to hold the lock to call this function. - - - - - - - a #GAsyncQueue. - - - - - - Decreases the reference count of the asynchronous @queue by 1 -and releases the lock. This function must be called while holding -the @queue's lock. If the reference count went to 0, the @queue -will be destroyed and the memory allocated will be freed. - Reference counting is done atomically. -so g_async_queue_unref() can be used regardless of the @queue's -lock. - - - - - - - a #GAsyncQueue - - - - - - Creates a new asynchronous queue. - - - a new #GAsyncQueue. Free with g_async_queue_unref() - - - - - Creates a new asynchronous queue and sets up a destroy notify -function that is used to free any remaining queue items when -the queue is destroyed after the final unref. - - - a new #GAsyncQueue. Free with g_async_queue_unref() - - - - - function to free queue elements - - - - - - - Specifies one of the possible types of byte order. -See #G_BYTE_ORDER. - - - - - The `GBookmarkFile` structure contains only -private data and should not be directly accessed. - - - Adds the application with @name and @exec to the list of -applications that have registered a bookmark for @uri into -@bookmark. - -Every bookmark inside a #GBookmarkFile must have at least an -application registered. Each application must provide a name, a -command line useful for launching the bookmark, the number of times -the bookmark has been registered by the application and the last -time the application registered this bookmark. - -If @name is %NULL, the name of the application will be the -same returned by g_get_application_name(); if @exec is %NULL, the -command line will be a composition of the program name as -returned by g_get_prgname() and the "\%u" modifier, which will be -expanded to the bookmark's URI. - -This function will automatically take care of updating the -registrations count and timestamping in case an application -with the same @name had already registered a bookmark for -@uri inside @bookmark. - -If no bookmark for @uri is found, one is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - the name of the application registering the bookmark - or %NULL - - - - command line to be used to launch the bookmark or %NULL - - - - - - Adds @group to the list of groups to which the bookmark for @uri -belongs to. - -If no bookmark for @uri is found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - the group name to be added - - - - - - Frees a #GBookmarkFile. - - - - - - - a #GBookmarkFile - - - - - - Gets the time the bookmark for @uri was added to @bookmark - -In the event the URI cannot be found, -1 is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a timestamp - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Gets the registration information of @app_name for the bookmark for -@uri. See g_bookmark_file_set_app_info() for more information about -the returned data. - -The string returned in @app_exec must be freed. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the -event that no application with name @app_name has registered a bookmark -for @uri, %FALSE is returned and error is set to -#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting -the command line fails, an error of the #G_SHELL_ERROR domain is -set and %FALSE is returned. - - - %TRUE on success. - - - - - a #GBookmarkFile - - - - a valid URI - - - - an application's name - - - - return location for the command line of the application, or %NULL - - - - return location for the registration count, or %NULL - - - - return location for the last registration time, or %NULL - - - - - - Retrieves the names of the applications that have registered the -bookmark for @uri. - -In the event the URI cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a newly allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - return location of the length of the returned list, or %NULL - - - - - - Retrieves the description of the bookmark for @uri. - -In the event the URI cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a newly allocated string or %NULL if the specified - URI cannot be found. - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Retrieves the list of group names of the bookmark for @uri. - -In the event the URI cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - -The returned array is %NULL terminated, so @length may optionally -be %NULL. - - - a newly allocated %NULL-terminated array of group names. - Use g_strfreev() to free it. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - return location for the length of the returned string, or %NULL - - - - - - Gets the icon of the bookmark for @uri. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - %TRUE if the icon for the bookmark for the URI was found. - You should free the returned strings. - - - - - a #GBookmarkFile - - - - a valid URI - - - - return location for the icon's location or %NULL - - - - return location for the icon's MIME type or %NULL - - - - - - Gets whether the private flag of the bookmark for @uri is set. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the -event that the private flag cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - - - %TRUE if the private flag is set, %FALSE otherwise. - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Retrieves the MIME type of the resource pointed by @uri. - -In the event the URI cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the -event that the MIME type cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - - - a newly allocated string or %NULL if the specified - URI cannot be found. - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Gets the time when the bookmark for @uri was last modified. - -In the event the URI cannot be found, -1 is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a timestamp - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Gets the number of bookmarks inside @bookmark. - - - the number of bookmarks - - - - - a #GBookmarkFile - - - - - - Returns the title of the bookmark for @uri. - -If @uri is %NULL, the title of @bookmark is returned. - -In the event the URI cannot be found, %NULL is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a newly allocated string or %NULL if the specified - URI cannot be found. - - - - - a #GBookmarkFile - - - - a valid URI or %NULL - - - - - - Returns all URIs of the bookmarks in the bookmark file @bookmark. -The array of returned URIs will be %NULL-terminated, so @length may -optionally be %NULL. - - - a newly allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. - - - - - - - a #GBookmarkFile - - - - return location for the number of returned URIs, or %NULL - - - - - - Gets the time the bookmark for @uri was last visited. - -In the event the URI cannot be found, -1 is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - a timestamp. - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Checks whether the bookmark for @uri inside @bookmark has been -registered by application @name. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - %TRUE if the application @name was found - - - - - a #GBookmarkFile - - - - a valid URI - - - - the name of the application - - - - - - Checks whether @group appears in the list of groups to which -the bookmark for @uri belongs to. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - %TRUE if @group was found. - - - - - a #GBookmarkFile - - - - a valid URI - - - - the group name to be searched - - - - - - Looks whether the desktop bookmark has an item with its URI set to @uri. - - - %TRUE if @uri is inside @bookmark, %FALSE otherwise - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Loads a bookmark file from memory into an empty #GBookmarkFile -structure. If the object cannot be created then @error is set to a -#GBookmarkFileError. - - - %TRUE if a desktop bookmark could be loaded. - - - - - an empty #GBookmarkFile struct - - - - desktop bookmarks - loaded in memory - - - - - - the length of @data in bytes - - - - - - This function looks for a desktop bookmark file named @file in the -paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), -loads the file into @bookmark and returns the file's full path in -@full_path. If the file could not be loaded then @error is -set to either a #GFileError or #GBookmarkFileError. - - - %TRUE if a key file could be loaded, %FALSE otherwise - - - - - a #GBookmarkFile - - - - a relative path to a filename to open and parse - - - - return location for a string - containing the full path of the file, or %NULL - - - - - - Loads a desktop bookmark file into an empty #GBookmarkFile structure. -If the file could not be loaded then @error is set to either a #GFileError -or #GBookmarkFileError. - - - %TRUE if a desktop bookmark file could be loaded - - - - - an empty #GBookmarkFile struct - - - - the path of a filename to load, in the - GLib file name encoding - - - - - - Changes the URI of a bookmark item from @old_uri to @new_uri. Any -existing bookmark for @new_uri will be overwritten. If @new_uri is -%NULL, then the bookmark is removed. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - - - %TRUE if the URI was successfully changed - - - - - a #GBookmarkFile - - - - a valid URI - - - - a valid URI, or %NULL - - - - - - Removes application registered with @name from the list of applications -that have registered a bookmark for @uri inside @bookmark. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. -In the event that no application with name @app_name has registered -a bookmark for @uri, %FALSE is returned and error is set to -#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. - - - %TRUE if the application was successfully removed. - - - - - a #GBookmarkFile - - - - a valid URI - - - - the name of the application - - - - - - Removes @group from the list of groups to which the bookmark -for @uri belongs to. - -In the event the URI cannot be found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. -In the event no group was defined, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - - - %TRUE if @group was successfully removed. - - - - - a #GBookmarkFile - - - - a valid URI - - - - the group name to be removed - - - - - - Removes the bookmark for @uri from the bookmark file @bookmark. - - - %TRUE if the bookmark was removed successfully. - - - - - a #GBookmarkFile - - - - a valid URI - - - - - - Sets the time the bookmark for @uri was added into @bookmark. - -If no bookmark for @uri is found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - a timestamp or -1 to use the current time - - - - - - Sets the meta-data of application @name inside the list of -applications that have registered a bookmark for @uri inside -@bookmark. - -You should rarely use this function; use g_bookmark_file_add_application() -and g_bookmark_file_remove_application() instead. - -@name can be any UTF-8 encoded string used to identify an -application. -@exec can have one of these two modifiers: "\%f", which will -be expanded as the local file name retrieved from the bookmark's -URI; "\%u", which will be expanded as the bookmark's URI. -The expansion is done automatically when retrieving the stored -command line using the g_bookmark_file_get_app_info() function. -@count is the number of times the application has registered the -bookmark; if is < 0, the current registration count will be increased -by one, if is 0, the application with @name will be removed from -the list of registered applications. -@stamp is the Unix time of the last registration; if it is -1, the -current time will be used. - -If you try to remove an application by setting its registration count to -zero, and no bookmark for @uri is found, %FALSE is returned and -@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, -in the event that no application @name has registered a bookmark -for @uri, %FALSE is returned and error is set to -#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark -for @uri is found, one is created. - - - %TRUE if the application's meta-data was successfully - changed. - - - - - a #GBookmarkFile - - - - a valid URI - - - - an application's name - - - - an application's command line - - - - the number of registrations done for this application - - - - the time of the last registration for this application - - - - - - Sets @description as the description of the bookmark for @uri. - -If @uri is %NULL, the description of @bookmark is set. - -If a bookmark for @uri cannot be found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI or %NULL - - - - a string - - - - - - Sets a list of group names for the item with URI @uri. Each previously -set group name list is removed. - -If @uri cannot be found then an item for it is created. - - - - - - - a #GBookmarkFile - - - - an item's URI - - - - an array of - group names, or %NULL to remove all groups - - - - - - number of group name values in @groups - - - - - - Sets the icon for the bookmark for @uri. If @href is %NULL, unsets -the currently set icon. @href can either be a full URL for the icon -file or the icon name following the Icon Naming specification. - -If no bookmark for @uri is found one is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - the URI of the icon for the bookmark, or %NULL - - - - the MIME type of the icon for the bookmark - - - - - - Sets the private flag of the bookmark for @uri. - -If a bookmark for @uri cannot be found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - %TRUE if the bookmark should be marked as private - - - - - - Sets @mime_type as the MIME type of the bookmark for @uri. - -If a bookmark for @uri cannot be found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - a MIME type - - - - - - Sets the last time the bookmark for @uri was last modified. - -If no bookmark for @uri is found then it is created. - -The "modified" time should only be set when the bookmark's meta-data -was actually changed. Every function of #GBookmarkFile that -modifies a bookmark also changes the modification time, except for -g_bookmark_file_set_visited(). - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - a timestamp or -1 to use the current time - - - - - - Sets @title as the title of the bookmark for @uri inside the -bookmark file @bookmark. - -If @uri is %NULL, the title of @bookmark is set. - -If a bookmark for @uri cannot be found then it is created. - - - - - - - a #GBookmarkFile - - - - a valid URI or %NULL - - - - a UTF-8 encoded string - - - - - - Sets the time the bookmark for @uri was last visited. - -If no bookmark for @uri is found then it is created. - -The "visited" time should only be set if the bookmark was launched, -either using the command line retrieved by g_bookmark_file_get_app_info() -or by the default application for the bookmark's MIME type, retrieved -using g_bookmark_file_get_mime_type(). Changing the "visited" time -does not affect the "modified" time. - - - - - - - a #GBookmarkFile - - - - a valid URI - - - - a timestamp or -1 to use the current time - - - - - - This function outputs @bookmark as a string. - - - - a newly allocated string holding the contents of the #GBookmarkFile - - - - - - - a #GBookmarkFile - - - - return location for the length of the returned string, or %NULL - - - - - - This function outputs @bookmark into a file. The write process is -guaranteed to be atomic by using g_file_set_contents() internally. - - - %TRUE if the file was successfully written. - - - - - a #GBookmarkFile - - - - path of the output file - - - - - - - - - - - Creates a new empty #GBookmarkFile object. - -Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() -or g_bookmark_file_load_from_data_dirs() to read an existing bookmark -file. - - - an empty #GBookmarkFile - - - - - - Error codes returned by bookmark file parsing. - - - URI was ill-formed - - - a requested field was not found - - - a requested application did - not register a bookmark - - - a requested URI was not found - - - document was ill formed - - - the text being parsed was - in an unknown encoding - - - an error occurred while writing - - - requested file was not found - - - - Contains the public fields of a GByteArray. - - - a pointer to the element data. The data may be moved as - elements are added to the #GByteArray - - - - the number of elements in the #GByteArray - - - - Adds the given bytes to the end of the #GByteArray. -The array will grow in size automatically if necessary. - - - the #GByteArray - - - - - - - a #GByteArray - - - - - - the byte data to be added - - - - the number of bytes to add - - - - - - Frees the memory allocated by the #GByteArray. If @free_segment is -%TRUE it frees the actual byte data. If the reference count of -@array is greater than one, the #GByteArray wrapper is preserved but -the size of @array will be set to zero. - - - the element data if @free_segment is %FALSE, otherwise - %NULL. The element data should be freed using g_free(). - - - - - a #GByteArray - - - - - - if %TRUE the actual byte data is freed as well - - - - - - Transfers the data from the #GByteArray into a new immutable #GBytes. - -The #GByteArray is freed unless the reference count of @array is greater -than one, the #GByteArray wrapper is preserved but the size of @array -will be set to zero. - -This is identical to using g_bytes_new_take() and g_byte_array_free() -together. - - - a new immutable #GBytes representing same - byte data that was in the array - - - - - a #GByteArray - - - - - - - - Creates a new #GByteArray with a reference count of 1. - - - the new #GByteArray - - - - - - - Create byte array containing the data. The data will be owned by the array -and will be freed with g_free(), i.e. it could be allocated using g_strdup(). - - - a new #GByteArray - - - - - - - byte data for the array - - - - - - length of @data - - - - - - Adds the given data to the start of the #GByteArray. -The array will grow in size automatically if necessary. - - - the #GByteArray - - - - - - - a #GByteArray - - - - - - the byte data to be added - - - - the number of bytes to add - - - - - - Atomically increments the reference count of @array by one. -This function is thread-safe and may be called from any thread. - - - The passed in #GByteArray - - - - - - - A #GByteArray - - - - - - - - Removes the byte at the given index from a #GByteArray. -The following bytes are moved down one place. - - - the #GByteArray - - - - - - - a #GByteArray - - - - - - the index of the byte to remove - - - - - - Removes the byte at the given index from a #GByteArray. The last -element in the array is used to fill in the space, so this function -does not preserve the order of the #GByteArray. But it is faster -than g_byte_array_remove_index(). - - - the #GByteArray - - - - - - - a #GByteArray - - - - - - the index of the byte to remove - - - - - - Removes the given number of bytes starting at the given index from a -#GByteArray. The following elements are moved to close the gap. - - - the #GByteArray - - - - - - - a @GByteArray - - - - - - the index of the first byte to remove - - - - the number of bytes to remove - - - - - - Sets the size of the #GByteArray, expanding it if necessary. - - - the #GByteArray - - - - - - - a #GByteArray - - - - - - the new size of the #GByteArray - - - - - - Creates a new #GByteArray with @reserved_size bytes preallocated. -This avoids frequent reallocation, if you are going to add many -bytes to the array. Note however that the size of the array is still -0. - - - the new #GByteArray - - - - - - - number of bytes preallocated - - - - - - Sorts a byte array, using @compare_func which should be a -qsort()-style comparison function (returns less than zero for first -arg is less than second arg, zero for equal, greater than zero if -first arg is greater than second arg). - -If two array elements compare equal, their order in the sorted array -is undefined. If you want equal elements to keep their order (i.e. -you want a stable sort) you can write a comparison function that, -if two elements would otherwise compare equal, compares them by -their addresses. - - - - - - - a #GByteArray - - - - - - comparison function - - - - - - Like g_byte_array_sort(), but the comparison function takes an extra -user data argument. - - - - - - - a #GByteArray - - - - - - comparison function - - - - data to pass to @compare_func - - - - - - Frees the data in the array and resets the size to zero, while -the underlying array is preserved for use elsewhere and returned -to the caller. - - - the element data, which should be - freed using g_free(). - - - - - a #GByteArray. - - - - - - pointer to retrieve the number of - elements of the original array - - - - - - Atomically decrements the reference count of @array by one. If the -reference count drops to 0, all memory allocated by the array is -released. This function is thread-safe and may be called from any -thread. - - - - - - - A #GByteArray - - - - - - - - - A simple refcounted data type representing an immutable sequence of zero or -more bytes from an unspecified origin. - -The purpose of a #GBytes is to keep the memory region that it holds -alive for as long as anyone holds a reference to the bytes. When -the last reference count is dropped, the memory is released. Multiple -unrelated callers can use byte data in the #GBytes without coordinating -their activities, resting assured that the byte data will not change or -move while they hold a reference. - -A #GBytes can come from many different origins that may have -different procedures for freeing the memory region. Examples are -memory from g_malloc(), from memory slices, from a #GMappedFile or -memory from other allocators. - -#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and -g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). -#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() -function to g_tree_new(). - -The data pointed to by this bytes must not be modified. For a mutable -array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a -mutable array for a #GBytes sequence. To create an immutable #GBytes from -a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. - - - Creates a new #GBytes from @data. - -@data is copied. If @size is 0, @data may be %NULL. - - - a new #GBytes - - - - - - the data to be used for the bytes - - - - - - the size of @data - - - - - - Creates a new #GBytes from static data. - -@data must be static (ie: never modified or freed). It may be %NULL if @size -is 0. - - - a new #GBytes - - - - - - the data to be used for the bytes - - - - - - the size of @data - - - - - - Creates a new #GBytes from @data. - -After this call, @data belongs to the bytes and may no longer be -modified by the caller. g_free() will be called on @data when the -bytes is no longer in use. Because of this @data must have been created by -a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many -functions that wrap these calls (such as g_new(), g_strdup(), etc). - -For creating #GBytes with memory from other allocators, see -g_bytes_new_with_free_func(). - -@data may be %NULL if @size is 0. - - - a new #GBytes - - - - - - the data to be used for the bytes - - - - - - the size of @data - - - - - - Creates a #GBytes from @data. - -When the last reference is dropped, @free_func will be called with the -@user_data argument. - -@data must not be modified after this call is made until @free_func has -been called to indicate that the bytes is no longer in use. - -@data may be %NULL if @size is 0. - - - a new #GBytes - - - - - - the data to be used for the bytes - - - - - - the size of @data - - - - the function to call to release the data - - - - data to pass to @free_func - - - - - - Compares the two #GBytes values. - -This function can be used to sort GBytes instances in lexicographical order. - -If @bytes1 and @bytes2 have different length but the shorter one is a -prefix of the longer one then the shorter one is considered to be less than -the longer one. Otherwise the first byte where both differ is used for -comparison. If @bytes1 has a smaller value at that position it is -considered less, otherwise greater than @bytes2. - - - a negative value if @bytes1 is less than @bytes2, a positive value - if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to - @bytes2 - - - - - a pointer to a #GBytes - - - - a pointer to a #GBytes to compare with @bytes1 - - - - - - Compares the two #GBytes values being pointed to and returns -%TRUE if they are equal. - -This function can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - - - %TRUE if the two keys match. - - - - - a pointer to a #GBytes - - - - a pointer to a #GBytes to compare with @bytes1 - - - - - - Get the byte data in the #GBytes. This data should not be modified. - -This function will always return the same pointer for a given #GBytes. - -%NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes -may represent an empty string with @data non-%NULL and @size as 0. %NULL will -not be returned if @size is non-zero. - - - - a pointer to the byte data, or %NULL - - - - - - - a #GBytes - - - - location to return size of byte data - - - - - - Get the size of the byte data in the #GBytes. - -This function will always return the same value for a given #GBytes. - - - the size - - - - - a #GBytes - - - - - - Creates an integer hash code for the byte data in the #GBytes. - -This function can be passed to g_hash_table_new() as the @key_hash_func -parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - - - a hash value corresponding to the key. - - - - - a pointer to a #GBytes key - - - - - - Creates a #GBytes which is a subsection of another #GBytes. The @offset + -@length may not be longer than the size of @bytes. - -A reference to @bytes will be held by the newly created #GBytes until -the byte data is no longer needed. - -Since 2.56, if @offset is 0 and @length matches the size of @bytes, then -@bytes will be returned with the reference count incremented by 1. If @bytes -is a slice of another #GBytes, then the resulting #GBytes will reference -the same #GBytes instead of @bytes. This allows consumers to simplify the -usage of #GBytes when asynchronously writing to streams. - - - a new #GBytes - - - - - a #GBytes - - - - offset which subsection starts at - - - - length of subsection - - - - - - Increase the reference count on @bytes. - - - the #GBytes - - - - - a #GBytes - - - - - - Releases a reference on @bytes. This may result in the bytes being -freed. If @bytes is %NULL, it will return immediately. - - - - - - - a #GBytes - - - - - - Unreferences the bytes, and returns a new mutable #GByteArray containing -the same byte data. - -As an optimization, the byte data is transferred to the array without copying -if this was the last reference to bytes and bytes was created with -g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all -other cases the data is copied. - - - a new mutable #GByteArray containing the same byte data - - - - - - - a #GBytes - - - - - - Unreferences the bytes, and returns a pointer the same byte data -contents. - -As an optimization, the byte data is returned without copying if this was -the last reference to bytes and bytes was created with g_bytes_new(), -g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the -data is copied. - - - a pointer to the same byte data, which should be - freed with g_free() - - - - - - - a #GBytes - - - - location to place the length of the returned data - - - - - - - Checks the version of the GLib library that is being compiled -against. See glib_check_version() for a runtime check. - - - - the major version to check for - - - the minor version to check for - - - the micro version to check for - - - - - The set of uppercase ASCII alphabet characters. -Used for specifying valid identifier characters -in #GScannerConfig. - - - - - The set of ASCII digits. -Used for specifying valid identifier characters -in #GScannerConfig. - - - - - The set of lowercase ASCII alphabet characters. -Used for specifying valid identifier characters -in #GScannerConfig. - - - - - An opaque structure representing a checksumming operation. -To create a new GChecksum, use g_checksum_new(). To free -a GChecksum, use g_checksum_free(). - - - Creates a new #GChecksum, using the checksum algorithm @checksum_type. -If the @checksum_type is not known, %NULL is returned. -A #GChecksum can be used to compute the checksum, or digest, of an -arbitrary binary blob, using different hashing algorithms. - -A #GChecksum works by feeding a binary blob through g_checksum_update() -until there is data to be checked; the digest can then be extracted -using g_checksum_get_string(), which will return the checksum as a -hexadecimal string; or g_checksum_get_digest(), which will return a -vector of raw bytes. Once either g_checksum_get_string() or -g_checksum_get_digest() have been called on a #GChecksum, the checksum -will be closed and it won't be possible to call g_checksum_update() -on it anymore. - - - the newly created #GChecksum, or %NULL. - Use g_checksum_free() to free the memory allocated by it. - - - - - the desired type of checksum - - - - - - Copies a #GChecksum. If @checksum has been closed, by calling -g_checksum_get_string() or g_checksum_get_digest(), the copied -checksum will be closed as well. - - - the copy of the passed #GChecksum. Use g_checksum_free() - when finished using it. - - - - - the #GChecksum to copy - - - - - - Frees the memory allocated for @checksum. - - - - - - - a #GChecksum - - - - - - Gets the digest from @checksum as a raw binary vector and places it -into @buffer. The size of the digest depends on the type of checksum. - -Once this function has been called, the #GChecksum is closed and can -no longer be updated with g_checksum_update(). - - - - - - - a #GChecksum - - - - output buffer - - - - - - an inout parameter. The caller initializes it to the size of @buffer. - After the call it contains the length of the digest. - - - - - - Gets the digest as a hexadecimal string. - -Once this function has been called the #GChecksum can no longer be -updated with g_checksum_update(). - -The hexadecimal characters will be lower case. - - - the hexadecimal representation of the checksum. The - returned string is owned by the checksum and should not be modified - or freed. - - - - - a #GChecksum - - - - - - Resets the state of the @checksum back to its initial state. - - - - - - - the #GChecksum to reset - - - - - - Feeds @data into an existing #GChecksum. The checksum must still be -open, that is g_checksum_get_string() or g_checksum_get_digest() must -not have been called on @checksum. - - - - - - - a #GChecksum - - - - buffer used to compute the checksum - - - - - - size of the buffer, or -1 if it is a null-terminated string. - - - - - - Gets the length in bytes of digests of type @checksum_type - - - the checksum length, or -1 if @checksum_type is -not supported. - - - - - a #GChecksumType - - - - - - - The hashing algorithm to be used by #GChecksum when performing the -digest of some data. - -Note that the #GChecksumType enumeration may be extended at a later -date to include new hashing algorithm types. - - - Use the MD5 hashing algorithm - - - Use the SHA-1 hashing algorithm - - - Use the SHA-256 hashing algorithm - - - Use the SHA-512 hashing algorithm (Since: 2.36) - - - Use the SHA-384 hashing algorithm (Since: 2.51) - - - - Prototype of a #GChildWatchSource callback, called when a child -process has exited. To interpret @status, see the documentation -for g_spawn_check_exit_status(). - - - - - - - the process id of the child process - - - - Status information about the child process, encoded - in a platform-specific manner - - - - user data passed to g_child_watch_add() - - - - - - Specifies the type of function passed to g_clear_handle_id(). -The implementation is expected to free the resource identified -by @handle_id; for instance, if @handle_id is a #GSource ID, -g_source_remove() can be used. - - - - - - - the handle ID to clear - - - - - - Specifies the type of a comparison function used to compare two -values. The function should return a negative integer if the first -value comes before the second, 0 if they are equal, or a positive -integer if the first value comes after the second. - - - negative value if @a < @b; zero if @a = @b; positive - value if @a > @b - - - - - a value - - - - a value to compare with - - - - user data - - - - - - Specifies the type of a comparison function used to compare two -values. The function should return a negative integer if the first -value comes before the second, 0 if they are equal, or a positive -integer if the first value comes after the second. - - - negative value if @a < @b; zero if @a = @b; positive - value if @a > @b - - - - - a value - - - - a value to compare with - - - - - - The #GCond struct is an opaque data structure that represents a -condition. Threads can block on a #GCond if they find a certain -condition to be false. If other threads change the state of this -condition they signal the #GCond, and that causes the waiting -threads to be woken up. - -Consider the following example of a shared variable. One or more -threads can wait for data to be published to the variable and when -another thread publishes the data, it can signal one of the waiting -threads to wake up to collect the data. - -Here is an example for using GCond to block a thread until a condition -is satisfied: -|[<!-- language="C" --> - gpointer current_data = NULL; - GMutex data_mutex; - GCond data_cond; - - void - push_data (gpointer data) - { - g_mutex_lock (&data_mutex); - current_data = data; - g_cond_signal (&data_cond); - g_mutex_unlock (&data_mutex); - } - - gpointer - pop_data (void) - { - gpointer data; - - g_mutex_lock (&data_mutex); - while (!current_data) - g_cond_wait (&data_cond, &data_mutex); - data = current_data; - current_data = NULL; - g_mutex_unlock (&data_mutex); - - return data; - } -]| -Whenever a thread calls pop_data() now, it will wait until -current_data is non-%NULL, i.e. until some other thread -has called push_data(). - -The example shows that use of a condition variable must always be -paired with a mutex. Without the use of a mutex, there would be a -race between the check of @current_data by the while loop in -pop_data() and waiting. Specifically, another thread could set -@current_data after the check, and signal the cond (with nobody -waiting on it) before the first thread goes to sleep. #GCond is -specifically useful for its ability to release the mutex and go -to sleep atomically. - -It is also important to use the g_cond_wait() and g_cond_wait_until() -functions only inside a loop which checks for the condition to be -true. See g_cond_wait() for an explanation of why the condition may -not be true even after it returns. - -If a #GCond is allocated in static storage then it can be used -without initialisation. Otherwise, you should call g_cond_init() -on it and g_cond_clear() when done. - -A #GCond should only be accessed via the g_cond_ functions. - - - - - - - - - - - If threads are waiting for @cond, all of them are unblocked. -If no threads are waiting for @cond, this function has no effect. -It is good practice to lock the same mutex as the waiting threads -while calling this function, though not required. - - - - - - - a #GCond - - - - - - Frees the resources allocated to a #GCond with g_cond_init(). - -This function should not be used with a #GCond that has been -statically allocated. - -Calling g_cond_clear() for a #GCond on which threads are -blocking leads to undefined behaviour. - - - - - - - an initialised #GCond - - - - - - Initialises a #GCond so that it can be used. - -This function is useful to initialise a #GCond that has been -allocated as part of a larger structure. It is not necessary to -initialise a #GCond that has been statically allocated. - -To undo the effect of g_cond_init() when a #GCond is no longer -needed, use g_cond_clear(). - -Calling g_cond_init() on an already-initialised #GCond leads -to undefined behaviour. - - - - - - - an uninitialized #GCond - - - - - - If threads are waiting for @cond, at least one of them is unblocked. -If no threads are waiting for @cond, this function has no effect. -It is good practice to hold the same lock as the waiting thread -while calling this function, though not required. - - - - - - - a #GCond - - - - - - Atomically releases @mutex and waits until @cond is signalled. -When this function returns, @mutex is locked again and owned by the -calling thread. - -When using condition variables, it is possible that a spurious wakeup -may occur (ie: g_cond_wait() returns even though g_cond_signal() was -not called). It's also possible that a stolen wakeup may occur. -This is when g_cond_signal() is called, but another thread acquires -@mutex before this thread and modifies the state of the program in -such a way that when g_cond_wait() is able to return, the expected -condition is no longer met. - -For this reason, g_cond_wait() must always be used in a loop. See -the documentation for #GCond for a complete example. - - - - - - - a #GCond - - - - a #GMutex that is currently locked - - - - - - Waits until either @cond is signalled or @end_time has passed. - -As with g_cond_wait() it is possible that a spurious or stolen wakeup -could occur. For that reason, waiting on a condition variable should -always be in a loop, based on an explicitly-checked predicate. - -%TRUE is returned if the condition variable was signalled (or in the -case of a spurious wakeup). %FALSE is returned if @end_time has -passed. - -The following code shows how to correctly perform a timed wait on a -condition variable (extending the example presented in the -documentation for #GCond): - -|[<!-- language="C" --> -gpointer -pop_data_timed (void) -{ - gint64 end_time; - gpointer data; - - g_mutex_lock (&data_mutex); - - end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND; - while (!current_data) - if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) - { - // timeout has passed. - g_mutex_unlock (&data_mutex); - return NULL; - } - - // there is data for us - data = current_data; - current_data = NULL; - - g_mutex_unlock (&data_mutex); - - return data; -} -]| - -Notice that the end time is calculated once, before entering the -loop and reused. This is the motivation behind the use of absolute -time on this API -- if a relative time of 5 seconds were passed -directly to the call and a spurious wakeup occurred, the program would -have to start over waiting again (which would lead to a total wait -time of more than 5 seconds). - - - %TRUE on a signal, %FALSE on a timeout - - - - - a #GCond - - - - a #GMutex that is currently locked - - - - the monotonic time to wait until - - - - - - - Error codes returned by character set conversion routines. - - - Conversion between the requested character - sets is not supported. - - - Invalid byte sequence in conversion input; - or the character sequence could not be represented in the target - character set. - - - Conversion failed for some reason. - - - Partial character sequence at end of input. - - - URI is invalid. - - - Pathname is not an absolute path. - - - No memory available. Since: 2.40 - - - An embedded NUL character is present in - conversion output where a NUL-terminated string is expected. - Since: 2.56 - - - - A function of this signature is used to copy the node data -when doing a deep-copy of a tree. - - - A pointer to the copy - - - - - A pointer to the data which should be copied - - - - Additional data - - - - - - A bitmask that restricts the possible flags passed to -g_datalist_set_flags(). Passing a flags value where -flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. - - - - - Represents an invalid #GDateDay. - - - - - Represents an invalid Julian day number. - - - - - Represents an invalid year. - - - - - Defines the appropriate cleanup function for a pointer type. - -The function will not be called if the variable to be cleaned up -contains %NULL. - -This will typically be the `_free()` or `_unref()` function for the given -type. - -With this definition, it will be possible to use g_autoptr() with -@TypeName. - -|[ -G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. - - - - a type name to define a g_autoptr() cleanup function for - - - the cleanup function - - - - - Defines the appropriate cleanup function for a type. - -This will typically be the `_clear()` function for the given type. - -With this definition, it will be possible to use g_auto() with -@TypeName. - -|[ -G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. - - - - a type name to define a g_auto() cleanup function for - - - the clear function - - - - - Defines the appropriate cleanup function for a type. - -With this definition, it will be possible to use g_auto() with -@TypeName. - -This function will be rarely used. It is used with pointer-based -typedefs and non-pointer types where the value of the variable -represents a resource that must be freed. Two examples are #GStrv -and file descriptors. - -@none specifies the "none" value for the type in question. It is -probably something like %NULL or `-1`. If the variable is found to -contain this value then the free function will not be called. - -|[ -G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. - - - - a type name to define a g_auto() cleanup function for - - - the free function - - - the "none" value for the type - - - - - A convenience macro which defines a function returning the -#GQuark for the name @QN. The function will be named -@q_n_quark(). - -Note that the quark name will be stringified automatically -in the macro, so you shouldn't use double quotes. - - - - the name to return a #GQuark for - - - prefix for the function name - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark -functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it -is meant to be portable across different compilers and must be placed -before the function declaration. - -|[<!-- language="C" -- -G_DEPRECATED_FOR(my_replacement) -int my_mistake (void); -]| - - - - the name of the function that this function was deprecated for - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The directory separator character. -This is '/' on UNIX machines and '\' under Windows. - - - - - The directory separator as a string. -This is "/" on UNIX machines and "\" under Windows. - - - - - The #GData struct is an opaque data structure to represent a -[Keyed Data List][glib-Keyed-Data-Lists]. It should only be -accessed via the following functions. - - - - Specifies the type of function passed to g_dataset_foreach(). It is -called with each #GQuark id and associated data element, together -with the @user_data parameter supplied to g_dataset_foreach(). - - - - - - - the #GQuark id to identifying the data element. - - - - the data element. - - - - user data passed to g_dataset_foreach(). - - - - - - Represents a day between January 1, Year 1 and a few thousand years in -the future. None of its members should be accessed directly. - -If the #GDate-struct is obtained from g_date_new(), it will be safe -to mutate but invalid and thus not safe for calendrical computations. - -If it's declared on the stack, it will contain garbage so must be -initialized with g_date_clear(). g_date_clear() makes the date invalid -but sane. An invalid date doesn't represent a day, it's "empty." A date -becomes valid after you set it to a Julian day or you set a day, month, -and year. - - - the Julian representation of the date - - - - this bit is set if @julian_days is valid - - - - this is set if @day, @month and @year are valid - - - - the day of the day-month-year representation of the date, - as a number between 1 and 31 - - - - the day of the day-month-year representation of the date, - as a number between 1 and 12 - - - - the day of the day-month-year representation of the date - - - - Allocates a #GDate and initializes -it to a sane state. The new date will -be cleared (as if you'd called g_date_clear()) but invalid (it won't -represent an existing day). Free the return value with g_date_free(). - - - a newly-allocated #GDate - - - - - Like g_date_new(), but also sets the value of the date. Assuming the -day-month-year triplet you pass in represents an existing day, the -returned date will be valid. - - - a newly-allocated #GDate initialized with @day, @month, and @year - - - - - day of the month - - - - month of the year - - - - year - - - - - - Like g_date_new(), but also sets the value of the date. Assuming the -Julian day number you pass in is valid (greater than 0, less than an -unreasonably large number), the returned date will be valid. - - - a newly-allocated #GDate initialized with @julian_day - - - - - days since January 1, Year 1 - - - - - - Increments a date some number of days. -To move forward by weeks, add weeks*7 days. -The date must be valid. - - - - - - - a #GDate to increment - - - - number of days to move the date forward - - - - - - Increments a date by some number of months. -If the day of the month is greater than 28, -this routine may change the day of the month -(because the destination month may not have -the current day in it). The date must be valid. - - - - - - - a #GDate to increment - - - - number of months to move forward - - - - - - Increments a date by some number of years. -If the date is February 29, and the destination -year is not a leap year, the date will be changed -to February 28. The date must be valid. - - - - - - - a #GDate to increment - - - - number of years to move forward - - - - - - If @date is prior to @min_date, sets @date equal to @min_date. -If @date falls after @max_date, sets @date equal to @max_date. -Otherwise, @date is unchanged. -Either of @min_date and @max_date may be %NULL. -All non-%NULL dates must be valid. - - - - - - - a #GDate to clamp - - - - minimum accepted value for @date - - - - maximum accepted value for @date - - - - - - Initializes one or more #GDate structs to a sane but invalid -state. The cleared dates will not represent an existing date, but will -not contain garbage. Useful to init a date declared on the stack. -Validity can be tested with g_date_valid(). - - - - - - - pointer to one or more dates to clear - - - - number of dates to clear - - - - - - qsort()-style comparison function for dates. -Both dates must be valid. - - - 0 for equal, less than zero if @lhs is less than @rhs, - greater than zero if @lhs is greater than @rhs - - - - - first date to compare - - - - second date to compare - - - - - - Copies a GDate to a newly-allocated GDate. If the input was invalid -(as determined by g_date_valid()), the invalid state will be copied -as is into the new object. - - - a newly-allocated #GDate initialized from @date - - - - - a #GDate to copy - - - - - - Computes the number of days between two dates. -If @date2 is prior to @date1, the returned value is negative. -Both dates must be valid. - - - the number of days between @date1 and @date2 - - - - - the first date - - - - the second date - - - - - - Frees a #GDate returned from g_date_new(). - - - - - - - a #GDate to free - - - - - - Returns the day of the month. The date must be valid. - - - day of the month - - - - - a #GDate to extract the day of the month from - - - - - - Returns the day of the year, where Jan 1 is the first day of the -year. The date must be valid. - - - day of the year - - - - - a #GDate to extract day of year from - - - - - - Returns the week of the year, where weeks are interpreted according -to ISO 8601. - - - ISO 8601 week number of the year. - - - - - a valid #GDate - - - - - - Returns the Julian day or "serial number" of the #GDate. The -Julian day is simply the number of days since January 1, Year 1; i.e., -January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, -etc. The date must be valid. - - - Julian day - - - - - a #GDate to extract the Julian day from - - - - - - Returns the week of the year, where weeks are understood to start on -Monday. If the date is before the first Monday of the year, return 0. -The date must be valid. - - - week of the year - - - - - a #GDate - - - - - - Returns the month of the year. The date must be valid. - - - month of the year as a #GDateMonth - - - - - a #GDate to get the month from - - - - - - Returns the week of the year during which this date falls, if -weeks are understood to begin on Sunday. The date must be valid. -Can return 0 if the day is before the first Sunday of the year. - - - week number - - - - - a #GDate - - - - - - Returns the day of the week for a #GDate. The date must be valid. - - - day of the week as a #GDateWeekday. - - - - - a #GDate - - - - - - Returns the year of a #GDate. The date must be valid. - - - year in which the date falls - - - - - a #GDate - - - - - - Returns %TRUE if the date is on the first of a month. -The date must be valid. - - - %TRUE if the date is the first of the month - - - - - a #GDate to check - - - - - - Returns %TRUE if the date is the last day of the month. -The date must be valid. - - - %TRUE if the date is the last day of the month - - - - - a #GDate to check - - - - - - Checks if @date1 is less than or equal to @date2, -and swap the values if this is not the case. - - - - - - - the first date - - - - the second date - - - - - - Sets the day of the month for a #GDate. If the resulting -day-month-year triplet is invalid, the date will be invalid. - - - - - - - a #GDate - - - - day to set - - - - - - Sets the value of a #GDate from a day, month, and year. -The day-month-year triplet must be valid; if you aren't -sure it is, call g_date_valid_dmy() to check before you -set it. - - - - - - - a #GDate - - - - day - - - - month - - - - year - - - - - - Sets the value of a #GDate from a Julian day number. - - - - - - - a #GDate - - - - Julian day number (days since January 1, Year 1) - - - - - - Sets the month of the year for a #GDate. If the resulting -day-month-year triplet is invalid, the date will be invalid. - - - - - - - a #GDate - - - - month to set - - - - - - Parses a user-inputted string @str, and try to figure out what date it -represents, taking the [current locale][setlocale] into account. If the -string is successfully parsed, the date will be valid after the call. -Otherwise, it will be invalid. You should check using g_date_valid() -to see whether the parsing succeeded. - -This function is not appropriate for file formats and the like; it -isn't very precise, and its exact behavior varies with the locale. -It's intended to be a heuristic routine that guesses what the user -means by a given string (and it does work pretty well in that -capacity). - - - - - - - a #GDate to fill in - - - - string to parse - - - - - - Sets the value of a date from a #GTime value. -The time to date conversion is done using the user's current timezone. - Use g_date_set_time_t() instead. - - - - - - - a #GDate. - - - - #GTime value to set. - - - - - - Sets the value of a date to the date corresponding to a time -specified as a time_t. The time to date conversion is done using -the user's current timezone. - -To set the value of a date to the current day, you could write: -|[<!-- language="C" --> - time_t now = time (NULL); - if (now == (time_t) -1) - // handle the error - g_date_set_time_t (date, now); -]| - - - - - - - a #GDate - - - - time_t value to set - - - - - - Sets the value of a date from a #GTimeVal value. Note that the -@tv_usec member is ignored, because #GDate can't make use of the -additional precision. - -The time to date conversion is done using the user's current timezone. - #GTimeVal is not year-2038-safe. Use g_date_set_time_t() - instead. - - - - - - - a #GDate - - - - #GTimeVal value to set - - - - - - Sets the year for a #GDate. If the resulting day-month-year -triplet is invalid, the date will be invalid. - - - - - - - a #GDate - - - - year to set - - - - - - Moves a date some number of days into the past. -To move by weeks, just move by weeks*7 days. -The date must be valid. - - - - - - - a #GDate to decrement - - - - number of days to move - - - - - - Moves a date some number of months into the past. -If the current day of the month doesn't exist in -the destination month, the day of the month -may change. The date must be valid. - - - - - - - a #GDate to decrement - - - - number of months to move - - - - - - Moves a date some number of years into the past. -If the current day doesn't exist in the destination -year (i.e. it's February 29 and you move to a non-leap-year) -then the day is changed to February 29. The date -must be valid. - - - - - - - a #GDate to decrement - - - - number of years to move - - - - - - Fills in the date-related bits of a struct tm using the @date value. -Initializes the non-date parts with something sane but meaningless. - - - - - - - a #GDate to set the struct tm from - - - - struct tm to fill - - - - - - Returns %TRUE if the #GDate represents an existing day. The date must not -contain garbage; it should have been initialized with g_date_clear() -if it wasn't allocated by one of the g_date_new() variants. - - - Whether the date is valid - - - - - a #GDate to check - - - - - - Returns the number of days in a month, taking leap -years into account. - - - number of days in @month during the @year - - - - - month - - - - year - - - - - - Returns the number of weeks in the year, where weeks -are taken to start on Monday. Will be 52 or 53. The -date must be valid. (Years always have 52 7-day periods, -plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many -Mondays are in the year, i.e. there are 53 Mondays if -one of the extra days happens to be a Monday.) - - - number of Mondays in the year - - - - - a year - - - - - - Returns the number of weeks in the year, where weeks -are taken to start on Sunday. Will be 52 or 53. The -date must be valid. (Years always have 52 7-day periods, -plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many -Sundays are in the year, i.e. there are 53 Sundays if -one of the extra days happens to be a Sunday.) - - - the number of weeks in @year - - - - - year to count weeks in - - - - - - Returns %TRUE if the year is a leap year. - -For the purposes of this function, leap year is every year -divisible by 4 unless that year is divisible by 100. If it -is divisible by 100 it would be a leap year only if that year -is also divisible by 400. - - - %TRUE if the year is a leap year - - - - - year to check - - - - - - Generates a printed representation of the date, in a -[locale][setlocale]-specific way. -Works just like the platform's C library strftime() function, -but only accepts date-related formats; time-related formats -give undefined results. Date must be valid. Unlike strftime() -(which uses the locale encoding), works on a UTF-8 format -string and stores a UTF-8 result. - -This function does not provide any conversion specifiers in -addition to those implemented by the platform's C library. -For example, don't expect that using g_date_strftime() would -make the \%F provided by the C99 strftime() work on Windows -where the C library only complies to C89. - - - number of characters written to the buffer, or 0 the buffer was too small - - - - - destination buffer - - - - buffer size - - - - format string - - - - valid #GDate - - - - - - Returns %TRUE if the day of the month is valid (a day is valid if it's -between 1 and 31 inclusive). - - - %TRUE if the day is valid - - - - - day to check - - - - - - Returns %TRUE if the day-month-year triplet forms a valid, existing day -in the range of days #GDate understands (Year 1 or later, no more than -a few thousand years in the future). - - - %TRUE if the date is a valid one - - - - - day - - - - month - - - - year - - - - - - Returns %TRUE if the Julian day is valid. Anything greater than zero -is basically a valid Julian, though there is a 32-bit limit. - - - %TRUE if the Julian day is valid - - - - - Julian day to check - - - - - - Returns %TRUE if the month value is valid. The 12 #GDateMonth -enumeration values are the only valid months. - - - %TRUE if the month is valid - - - - - month - - - - - - Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration -values are the only valid weekdays. - - - %TRUE if the weekday is valid - - - - - weekday - - - - - - Returns %TRUE if the year is valid. Any year greater than 0 is valid, -though there is a 16-bit limit to what #GDate will understand. - - - %TRUE if the year is valid - - - - - year - - - - - - - This enumeration isn't used in the API, but may be useful if you need -to mark a number as a day, month, or year. - - - a day - - - a month - - - a year - - - - Enumeration representing a month; values are #G_DATE_JANUARY, -#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. - - - invalid value - - - January - - - February - - - March - - - April - - - May - - - June - - - July - - - August - - - September - - - October - - - November - - - December - - - - `GDateTime` is an opaque structure whose members -cannot be accessed directly. - - - Creates a new #GDateTime corresponding to the given date and time in -the time zone @tz. - -The @year must be between 1 and 9999, @month between 1 and 12 and @day -between 1 and 28, 29, 30 or 31 depending on the month and the year. - -@hour must be between 0 and 23 and @minute must be between 0 and 59. - -@seconds must be at least 0.0 and must be strictly less than 60.0. -It will be rounded down to the nearest microsecond. - -If the given time is not representable in the given time zone (for -example, 02:30 on March 14th 2010 in Toronto, due to daylight savings -time) then the time will be rounded up to the nearest existing time -(in this case, 03:00). If this matters to you then you should verify -the return value for containing the same as the numbers you gave. - -In the case that the given time is ambiguous in the given time zone -(for example, 01:30 on November 7th 2010 in Toronto, due to daylight -savings time) then the time falling within standard (ie: -non-daylight) time is taken. - -It not considered a programmer error for the values to this function -to be out of range, but in the case that they are, the function will -return %NULL. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - a #GTimeZone - - - - the year component of the date - - - - the month component of the date - - - - the day component of the date - - - - the hour component of the date - - - - the minute component of the date - - - - the number of seconds past the minute - - - - - - Creates a #GDateTime corresponding to the given -[ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) -@text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with -some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as -mentioned below. - -Note that as #GDateTime "is oblivious to leap seconds", leap seconds information -in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as -`23:59:59`. - -<sep> is the separator and can be either 'T', 't' or ' '. The latter two -separators are an extension from -[RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). - -<date> is in the form: - -- `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24. -- `YYYYMMDD` - Same as above without dividers. -- `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237. -- `YYYYDDD` - Same as above without dividers. -- `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7, - e.g. 2016-W34-3. -- `YYYYWwwD` - Same as above without dividers. - -<time> is in the form: - -- `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123. -- `hhmmss(.sss)` - Same as above without dividers. - -<tz> is an optional timezone suffix of the form: - -- `Z` - UTC. -- `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00. -- `+hh` or `-hh` - Offset from UTC in hours, e.g. +12. - -If the timezone is not provided in @text it must be provided in @default_tz -(this field is otherwise ignored). - -This call can fail (returning %NULL) if @text is not a valid ISO 8601 -formatted string. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - an ISO 8601 formatted time string. - - - - a #GTimeZone to use if the text doesn't contain a - timezone, or %NULL. - - - - - - Creates a #GDateTime corresponding to the given #GTimeVal @tv in the -local time zone. - -The time contained in a #GTimeVal is always stored in the form of -seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the -local time offset. - -This call can fail (returning %NULL) if @tv represents a time outside -of the supported range of #GDateTime. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - #GTimeVal is not year-2038-safe. Use - g_date_time_new_from_unix_local() instead. - - - a new #GDateTime, or %NULL - - - - - a #GTimeVal - - - - - - Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. - -The time contained in a #GTimeVal is always stored in the form of -seconds elapsed since 1970-01-01 00:00:00 UTC. - -This call can fail (returning %NULL) if @tv represents a time outside -of the supported range of #GDateTime. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - #GTimeVal is not year-2038-safe. Use - g_date_time_new_from_unix_utc() instead. - - - a new #GDateTime, or %NULL - - - - - a #GTimeVal - - - - - - Creates a #GDateTime corresponding to the given Unix time @t in the -local time zone. - -Unix time is the number of seconds that have elapsed since 1970-01-01 -00:00:00 UTC, regardless of the local time offset. - -This call can fail (returning %NULL) if @t represents a time outside -of the supported range of #GDateTime. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - the Unix time - - - - - - Creates a #GDateTime corresponding to the given Unix time @t in UTC. - -Unix time is the number of seconds that have elapsed since 1970-01-01 -00:00:00 UTC. - -This call can fail (returning %NULL) if @t represents a time outside -of the supported range of #GDateTime. - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - the Unix time - - - - - - Creates a new #GDateTime corresponding to the given date and time in -the local time zone. - -This call is equivalent to calling g_date_time_new() with the time -zone returned by g_time_zone_new_local(). - - - a #GDateTime, or %NULL - - - - - the year component of the date - - - - the month component of the date - - - - the day component of the date - - - - the hour component of the date - - - - the minute component of the date - - - - the number of seconds past the minute - - - - - - Creates a #GDateTime corresponding to this exact instant in the given -time zone @tz. The time is as accurate as the system allows, to a -maximum accuracy of 1 microsecond. - -This function will always succeed unless the system clock is set to -truly insane values (or unless GLib is still being used after the -year 9999). - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - a #GTimeZone - - - - - - Creates a #GDateTime corresponding to this exact instant in the local -time zone. - -This is equivalent to calling g_date_time_new_now() with the time -zone returned by g_time_zone_new_local(). - - - a new #GDateTime, or %NULL - - - - - Creates a #GDateTime corresponding to this exact instant in UTC. - -This is equivalent to calling g_date_time_new_now() with the time -zone returned by g_time_zone_new_utc(). - - - a new #GDateTime, or %NULL - - - - - Creates a new #GDateTime corresponding to the given date and time in -UTC. - -This call is equivalent to calling g_date_time_new() with the time -zone returned by g_time_zone_new_utc(). - - - a #GDateTime, or %NULL - - - - - the year component of the date - - - - the month component of the date - - - - the day component of the date - - - - the hour component of the date - - - - the minute component of the date - - - - the number of seconds past the minute - - - - - - Creates a copy of @datetime and adds the specified timespan to the copy. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - a #GTimeSpan - - - - - - Creates a copy of @datetime and adds the specified number of days to the -copy. Add negative values to subtract days. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of days - - - - - - Creates a new #GDateTime adding the specified values to the current date and -time in @datetime. Add negative values to subtract. - - - the newly created #GDateTime that should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of years to add - - - - the number of months to add - - - - the number of days to add - - - - the number of hours to add - - - - the number of minutes to add - - - - the number of seconds to add - - - - - - Creates a copy of @datetime and adds the specified number of hours. -Add negative values to subtract hours. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of hours to add - - - - - - Creates a copy of @datetime adding the specified number of minutes. -Add negative values to subtract minutes. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of minutes to add - - - - - - Creates a copy of @datetime and adds the specified number of months to the -copy. Add negative values to subtract months. - -The day of the month of the resulting #GDateTime is clamped to the number -of days in the updated calendar month. For example, if adding 1 month to -31st January 2018, the result would be 28th February 2018. In 2020 (a leap -year), the result would be 29th February. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of months - - - - - - Creates a copy of @datetime and adds the specified number of seconds. -Add negative values to subtract seconds. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of seconds to add - - - - - - Creates a copy of @datetime and adds the specified number of weeks to the -copy. Add negative values to subtract weeks. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of weeks - - - - - - Creates a copy of @datetime and adds the specified number of years to the -copy. Add negative values to subtract years. - -As with g_date_time_add_months(), if the resulting date would be 29th -February on a non-leap year, the day will be clamped to 28th February. - - - the newly created #GDateTime which should be freed with - g_date_time_unref(). - - - - - a #GDateTime - - - - the number of years - - - - - - Calculates the difference in time between @end and @begin. The -#GTimeSpan that is returned is effectively @end - @begin (ie: -positive if the first parameter is larger). - - - the difference between the two #GDateTime, as a time - span expressed in microseconds. - - - - - a #GDateTime - - - - a #GDateTime - - - - - - Creates a newly allocated string representing the requested @format. - -The format strings understood by this function are a subset of the -strftime() format language as specified by C99. The \%D, \%U and \%W -conversions are not supported, nor is the 'E' modifier. The GNU -extensions \%k, \%l, \%s and \%P are supported, however, as are the -'0', '_' and '-' modifiers. - -In contrast to strftime(), this function always produces a UTF-8 -string, regardless of the current locale. Note that the rendering of -many formats is locale-dependent and may not match the strftime() -output exactly. - -The following format specifiers are supported: - -- \%a: the abbreviated weekday name according to the current locale -- \%A: the full weekday name according to the current locale -- \%b: the abbreviated month name according to the current locale -- \%B: the full month name according to the current locale -- \%c: the preferred date and time representation for the current locale -- \%C: the century number (year/100) as a 2-digit integer (00-99) -- \%d: the day of the month as a decimal number (range 01 to 31) -- \%e: the day of the month as a decimal number (range 1 to 31) -- \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) -- \%g: the last two digits of the ISO 8601 week-based year as a - decimal number (00-99). This works well with \%V and \%u. -- \%G: the ISO 8601 week-based year as a decimal number. This works - well with \%V and \%u. -- \%h: equivalent to \%b -- \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) -- \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) -- \%j: the day of the year as a decimal number (range 001 to 366) -- \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); - single digits are preceded by a blank -- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); - single digits are preceded by a blank -- \%m: the month as a decimal number (range 01 to 12) -- \%M: the minute as a decimal number (range 00 to 59) -- \%p: either "AM" or "PM" according to the given time value, or the - corresponding strings for the current locale. Noon is treated as - "PM" and midnight as "AM". -- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for - the current locale -- \%r: the time in a.m. or p.m. notation -- \%R: the time in 24-hour notation (\%H:\%M) -- \%s: the number of seconds since the Epoch, that is, since 1970-01-01 - 00:00:00 UTC -- \%S: the second as a decimal number (range 00 to 60) -- \%t: a tab character -- \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) -- \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, - Monday being 1. This works well with \%G and \%V. -- \%V: the ISO 8601 standard week number of the current year as a decimal - number, range 01 to 53, where week 1 is the first week that has at - least 4 days in the new year. See g_date_time_get_week_of_year(). - This works well with \%G and \%u. -- \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. - This is not the ISO 8601 standard format -- use \%u instead. -- \%x: the preferred date representation for the current locale without - the time -- \%X: the preferred time representation for the current locale without - the date -- \%y: the year as a decimal number without the century -- \%Y: the year as a decimal number including the century -- \%z: the time zone as an offset from UTC (+hhmm) -- \%:z: the time zone as an offset from UTC (+hh:mm). - This is a gnulib strftime() extension. Since: 2.38 -- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a - gnulib strftime() extension. Since: 2.38 -- \%:::z: the time zone as an offset from UTC, with : to necessary - precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 -- \%Z: the time zone or name or abbreviation -- \%\%: a literal \% character - -Some conversion specifications can be modified by preceding the -conversion specifier by one or more modifier characters. The -following modifiers are supported for many of the numeric -conversions: - -- O: Use alternative numeric symbols, if the current locale supports those. -- _: Pad a numeric result with spaces. This overrides the default padding - for the specifier. -- -: Do not pad a numeric result. This overrides the default padding - for the specifier. -- 0: Pad a numeric result with zeros. This overrides the default padding - for the specifier. - -Additionally, when O is used with B, b, or h, it produces the alternative -form of a month name. The alternative form should be used when the month -name is used without a day number (e.g., standalone). It is required in -some languages (Baltic, Slavic, Greek, and more) due to their grammatical -rules. For other languages there is no difference. \%OB is a GNU and BSD -strftime() extension expected to be added to the future POSIX specification, -\%Ob and \%Oh are GNU strftime() extensions. Since: 2.56 - - - a newly allocated string formatted to the requested format - or %NULL in the case that there was an error (such as a format specifier - not being supported in the current locale). The string - should be freed with g_free(). - - - - - A #GDateTime - - - - a valid UTF-8 string, containing the format for the - #GDateTime - - - - - - Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), -including the date, time and time zone, and return that as a UTF-8 encoded -string. - - - a newly allocated string formatted in ISO 8601 format - or %NULL in the case that there was an error. The string - should be freed with g_free(). - - - - - A #GDateTime - - - - - - Retrieves the day of the month represented by @datetime in the gregorian -calendar. - - - the day of the month - - - - - a #GDateTime - - - - - - Retrieves the ISO 8601 day of the week on which @datetime falls (1 is -Monday, 2 is Tuesday... 7 is Sunday). - - - the day of the week - - - - - a #GDateTime - - - - - - Retrieves the day of the year represented by @datetime in the Gregorian -calendar. - - - the day of the year - - - - - a #GDateTime - - - - - - Retrieves the hour of the day represented by @datetime - - - the hour of the day - - - - - a #GDateTime - - - - - - Retrieves the microsecond of the date represented by @datetime - - - the microsecond of the second - - - - - a #GDateTime - - - - - - Retrieves the minute of the hour represented by @datetime - - - the minute of the hour - - - - - a #GDateTime - - - - - - Retrieves the month of the year represented by @datetime in the Gregorian -calendar. - - - the month represented by @datetime - - - - - a #GDateTime - - - - - - Retrieves the second of the minute represented by @datetime - - - the second represented by @datetime - - - - - a #GDateTime - - - - - - Retrieves the number of seconds since the start of the last minute, -including the fractional part. - - - the number of seconds - - - - - a #GDateTime - - - - - - Get the time zone for this @datetime. - - - the time zone - - - - - a #GDateTime - - - - - - Determines the time zone abbreviation to be used at the time and in -the time zone of @datetime. - -For example, in Toronto this is currently "EST" during the winter -months and "EDT" during the summer months when daylight savings -time is in effect. - - - the time zone abbreviation. The returned - string is owned by the #GDateTime and it should not be - modified or freed - - - - - a #GDateTime - - - - - - Determines the offset to UTC in effect at the time and in the time -zone of @datetime. - -The offset is the number of microseconds that you add to UTC time to -arrive at local time for the time zone (ie: negative numbers for time -zones west of GMT, positive numbers for east). - -If @datetime represents UTC time, then the offset is always zero. - - - the number of microseconds that should be added to UTC to - get the local time - - - - - a #GDateTime - - - - - - Returns the ISO 8601 week-numbering year in which the week containing -@datetime falls. - -This function, taken together with g_date_time_get_week_of_year() and -g_date_time_get_day_of_week() can be used to determine the full ISO -week date on which @datetime falls. - -This is usually equal to the normal Gregorian year (as returned by -g_date_time_get_year()), except as detailed below: - -For Thursday, the week-numbering year is always equal to the usual -calendar year. For other days, the number is such that every day -within a complete week (Monday to Sunday) is contained within the -same week-numbering year. - -For Monday, Tuesday and Wednesday occurring near the end of the year, -this may mean that the week-numbering year is one greater than the -calendar year (so that these days have the same week-numbering year -as the Thursday occurring early in the next year). - -For Friday, Saturday and Sunday occurring near the start of the year, -this may mean that the week-numbering year is one less than the -calendar year (so that these days have the same week-numbering year -as the Thursday occurring late in the previous year). - -An equivalent description is that the week-numbering year is equal to -the calendar year containing the majority of the days in the current -week (Monday to Sunday). - -Note that January 1 0001 in the proleptic Gregorian calendar is a -Monday, so this function never returns 0. - - - the ISO 8601 week-numbering year for @datetime - - - - - a #GDateTime - - - - - - Returns the ISO 8601 week number for the week containing @datetime. -The ISO 8601 week number is the same for every day of the week (from -Moday through Sunday). That can produce some unusual results -(described below). - -The first week of the year is week 1. This is the week that contains -the first Thursday of the year. Equivalently, this is the first week -that has more than 4 of its days falling within the calendar year. - -The value 0 is never returned by this function. Days contained -within a year but occurring before the first ISO 8601 week of that -year are considered as being contained in the last week of the -previous year. Similarly, the final days of a calendar year may be -considered as being part of the first ISO 8601 week of the next year -if 4 or more days of that week are contained within the new year. - - - the ISO 8601 week number for @datetime. - - - - - a #GDateTime - - - - - - Retrieves the year represented by @datetime in the Gregorian calendar. - - - the year represented by @datetime - - - - - A #GDateTime - - - - - - Retrieves the Gregorian day, month, and year of a given #GDateTime. - - - - - - - a #GDateTime. - - - - the return location for the gregorian year, or %NULL. - - - - the return location for the month of the year, or %NULL. - - - - the return location for the day of the month, or %NULL. - - - - - - Determines if daylight savings time is in effect at the time and in -the time zone of @datetime. - - - %TRUE if daylight savings time is in effect - - - - - a #GDateTime - - - - - - Atomically increments the reference count of @datetime by one. - - - the #GDateTime with the reference count increased - - - - - a #GDateTime - - - - - - Creates a new #GDateTime corresponding to the same instant in time as -@datetime, but in the local time zone. - -This call is equivalent to calling g_date_time_to_timezone() with the -time zone returned by g_time_zone_new_local(). - - - the newly created #GDateTime - - - - - a #GDateTime - - - - - - Stores the instant in time that @datetime represents into @tv. - -The time contained in a #GTimeVal is always stored in the form of -seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time -zone associated with @datetime. - -On systems where 'long' is 32bit (ie: all 32bit systems and all -Windows systems), a #GTimeVal is incapable of storing the entire -range of values that #GDateTime is capable of expressing. On those -systems, this function returns %FALSE to indicate that the time is -out of range. - -On systems where 'long' is 64bit, this function never fails. - #GTimeVal is not year-2038-safe. Use - g_date_time_to_unix() instead. - - - %TRUE if successful, else %FALSE - - - - - a #GDateTime - - - - a #GTimeVal to modify - - - - - - Create a new #GDateTime corresponding to the same instant in time as -@datetime, but in the time zone @tz. - -This call can fail in the case that the time goes out of bounds. For -example, converting 0001-01-01 00:00:00 UTC to a time zone west of -Greenwich will fail (due to the year 0 being out of range). - -You should release the return value by calling g_date_time_unref() -when you are done with it. - - - a new #GDateTime, or %NULL - - - - - a #GDateTime - - - - the new #GTimeZone - - - - - - Gives the Unix time corresponding to @datetime, rounding down to the -nearest second. - -Unix time is the number of seconds that have elapsed since 1970-01-01 -00:00:00 UTC, regardless of the time zone associated with @datetime. - - - the Unix time corresponding to @datetime - - - - - a #GDateTime - - - - - - Creates a new #GDateTime corresponding to the same instant in time as -@datetime, but in UTC. - -This call is equivalent to calling g_date_time_to_timezone() with the -time zone returned by g_time_zone_new_utc(). - - - the newly created #GDateTime - - - - - a #GDateTime - - - - - - Atomically decrements the reference count of @datetime by one. - -When the reference count reaches zero, the resources allocated by -@datetime are freed - - - - - - - a #GDateTime - - - - - - A comparison function for #GDateTimes that is suitable -as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - - - -1, 0 or 1 if @dt1 is less than, equal to or greater - than @dt2. - - - - - first #GDateTime to compare - - - - second #GDateTime to compare - - - - - - Checks to see if @dt1 and @dt2 are equal. - -Equal here means that they represent the same moment after converting -them to the same time zone. - - - %TRUE if @dt1 and @dt2 are equal - - - - - a #GDateTime - - - - a #GDateTime - - - - - - Hashes @datetime into a #guint, suitable for use within #GHashTable. - - - a #guint containing the hash - - - - - a #GDateTime - - - - - - - Enumeration representing a day of the week; #G_DATE_MONDAY, -#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. - - - invalid value - - - Monday - - - Tuesday - - - Wednesday - - - Thursday - - - Friday - - - Saturday - - - Sunday - - - - Associates a string with a bit flag. -Used in g_parse_debug_string(). - - - the string - - - - the flag - - - - - Specifies the type of function which is called when a data element -is destroyed. It is passed the pointer to the data element and -should free any memory and resources allocated for it. - - - - - - - the data element. - - - - - - An opaque structure representing an opened directory. - - - Closes the directory and deallocates all related resources. - - - - - - - a #GDir* created by g_dir_open() - - - - - - Retrieves the name of another entry in the directory, or %NULL. -The order of entries returned from this function is not defined, -and may vary by file system or other operating-system dependent -factors. - -%NULL may also be returned in case of errors. On Unix, you can -check `errno` to find out if %NULL was returned because of an error. - -On Unix, the '.' and '..' entries are omitted, and the returned -name is in the on-disk encoding. - -On Windows, as is true of all GLib functions which operate on -filenames, the returned name is in UTF-8. - - - The entry's name or %NULL if there are no - more entries. The return value is owned by GLib and - must not be modified or freed. - - - - - a #GDir* created by g_dir_open() - - - - - - Resets the given directory. The next call to g_dir_read_name() -will return the first entry again. - - - - - - - a #GDir* created by g_dir_open() - - - - - - Creates a subdirectory in the preferred directory for temporary -files (as returned by g_get_tmp_dir()). - -@tmpl should be a string in the GLib file name encoding containing -a sequence of six 'X' characters, as the parameter to g_mkstemp(). -However, unlike these functions, the template should only be a -basename, no directory components are allowed. If template is -%NULL, a default template is used. - -Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not -modified, and might thus be a read-only literal string. - - - The actual name used. This string - should be freed with g_free() when not needed any longer and is - is in the GLib file name encoding. In case of errors, %NULL is - returned and @error will be set. - - - - - Template for directory name, - as in g_mkdtemp(), basename only, or %NULL for a default template - - - - - - Opens a directory for reading. The names of the files in the -directory can then be retrieved using g_dir_read_name(). Note -that the ordering is not defined. - - - a newly allocated #GDir on success, %NULL on failure. - If non-%NULL, you must free the result with g_dir_close() - when you are finished with it. - - - - - the path to the directory you are interested in. On Unix - in the on-disk encoding. On Windows in UTF-8 - - - - Currently must be set to 0. Reserved for future use. - - - - - - - The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, -mantissa and exponent of IEEE floats and doubles. These unions are defined -as appropriate for a given platform. IEEE floats and doubles are supported -(used for storage) by at least Intel, PPC and Sparc. - - - the double value - - - - - - - - - - - - - - - - - - - - The type of functions that are used to 'duplicate' an object. -What this means depends on the context, it could just be -incrementing the reference count, if @data is a ref-counted -object. - - - a duplicate of data - - - - - the data to duplicate - - - - user data that was specified in - g_datalist_id_dup_data() - - - - - - The base of natural logarithms. - - - - - - - - - - - - - - Specifies the type of a function used to test two values for -equality. The function should return %TRUE if both values are equal -and %FALSE otherwise. - - - %TRUE if @a = @b; %FALSE otherwise - - - - - a value - - - - a value to compare with - - - - - - The `GError` structure contains information about -an error that has occurred. - - - error domain, e.g. #G_FILE_ERROR - - - - error code, e.g. %G_FILE_ERROR_NOENT - - - - human-readable informative error message - - - - Creates a new #GError with the given @domain and @code, -and a message formatted with @format. - - - a new #GError - - - - - error domain - - - - error code - - - - printf()-style format for error message - - - - parameters for message format - - - - - - Creates a new #GError; unlike g_error_new(), @message is -not a printf()-style format string. Use this function if -@message contains text you don't have control over, -that could include printf() escape sequences. - - - a new #GError - - - - - error domain - - - - error code - - - - error message - - - - - - Creates a new #GError with the given @domain and @code, -and a message formatted with @format. - - - a new #GError - - - - - error domain - - - - error code - - - - printf()-style format for error message - - - - #va_list of parameters for the message format - - - - - - Makes a copy of @error. - - - a new #GError - - - - - a #GError - - - - - - Frees a #GError and associated resources. - - - - - - - a #GError - - - - - - Returns %TRUE if @error matches @domain and @code, %FALSE -otherwise. In particular, when @error is %NULL, %FALSE will -be returned. - -If @domain contains a `FAILED` (or otherwise generic) error code, -you should generally not check for it explicitly, but should -instead treat any not-explicitly-recognized error code as being -equivalent to the `FAILED` code. This way, if the domain is -extended in the future to provide a more specific error code for -a certain case, your code will still work. - - - whether @error has @domain and @code - - - - - a #GError - - - - an error domain - - - - an error code - - - - - - - The possible errors, used in the @v_error field -of #GTokenValue, when the token is a %G_TOKEN_ERROR. - - - unknown error - - - unexpected end of file - - - unterminated string constant - - - unterminated comment - - - non-digit character in a number - - - digit beyond radix in a number - - - non-decimal floating point number - - - malformed floating point number - - - - Values corresponding to @errno codes returned from file operations -on UNIX. Unlike @errno codes, GFileError values are available on -all systems, even Windows. The exact meaning of each code depends -on what sort of file operation you were performing; the UNIX -documentation gives more details. The following error code descriptions -come from the GNU C Library manual, and are under the copyright -of that manual. - -It's not very portable to make detailed assumptions about exactly -which errors will be returned from a given operation. Some errors -don't occur on some systems, etc., sometimes there are subtle -differences in when a system will report a given error, etc. - - - Operation not permitted; only the owner of - the file (or other resource) or processes with special privileges - can perform the operation. - - - File is a directory; you cannot open a directory - for writing, or create or remove hard links to it. - - - Permission denied; the file permissions do not - allow the attempted operation. - - - Filename too long. - - - No such file or directory. This is a "file - doesn't exist" error for ordinary files that are referenced in - contexts where they are expected to already exist. - - - A file that isn't a directory was specified when - a directory is required. - - - No such device or address. The system tried to - use the device represented by a file you specified, and it - couldn't find the device. This can mean that the device file was - installed incorrectly, or that the physical device is missing or - not correctly attached to the computer. - - - The underlying file system of the specified file - does not support memory mapping. - - - The directory containing the new link can't be - modified because it's on a read-only file system. - - - Text file busy. - - - You passed in a pointer to bad memory. - (GLib won't reliably return this, don't pass in pointers to bad - memory.) - - - Too many levels of symbolic links were encountered - in looking up a file name. This often indicates a cycle of symbolic - links. - - - No space left on device; write operation on a - file failed because the disk is full. - - - No memory available. The system cannot allocate - more virtual memory because its capacity is full. - - - The current process has too many files open and - can't open any more. Duplicate descriptors do count toward this - limit. - - - There are too many distinct file openings in the - entire system. - - - Bad file descriptor; for example, I/O on a - descriptor that has been closed or reading from a descriptor open - only for writing (or vice versa). - - - Invalid argument. This is used to indicate - various kinds of problems with passing the wrong argument to a - library function. - - - Broken pipe; there is no process reading from the - other end of a pipe. Every library function that returns this - error code also generates a 'SIGPIPE' signal; this signal - terminates the program if not handled or blocked. Thus, your - program will never actually see this code unless it has handled - or blocked 'SIGPIPE'. - - - Resource temporarily unavailable; the call might - work if you try again later. - - - Interrupted function call; an asynchronous signal - occurred and prevented completion of the call. When this - happens, you should try the call again. - - - Input/output error; usually used for physical read - or write errors. i.e. the disk or other physical device hardware - is returning errors. - - - Operation not permitted; only the owner of the - file (or other resource) or processes with special privileges can - perform the operation. - - - Function not implemented; this indicates that - the system is missing some functionality. - - - Does not correspond to a UNIX error code; this - is the standard "failed for unspecified reason" error code present - in all #GError error code enumerations. Returned if no specific - code applies. - - - - A test to perform on a file using g_file_test(). - - - %TRUE if the file is a regular file - (not a directory). Note that this test will also return %TRUE - if the tested file is a symlink to a regular file. - - - %TRUE if the file is a symlink. - - - %TRUE if the file is a directory. - - - %TRUE if the file is executable. - - - %TRUE if the file exists. It may or may not - be a regular file. - - - - The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, -mantissa and exponent of IEEE floats and doubles. These unions are defined -as appropriate for a given platform. IEEE floats and doubles are supported -(used for storage) by at least Intel, PPC and Sparc. - - - the double value - - - - - - - - - - - - - - - - - Flags to modify the format of the string returned by g_format_size_full(). - - - behave the same as g_format_size() - - - include the exact number of bytes as part - of the returned string. For example, "45.6 kB (45,612 bytes)". - - - use IEC (base 1024) units with "KiB"-style - suffixes. IEC units should only be used for reporting things with - a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. - Network and storage sizes should be reported in the normal SI units. - - - set the size as a quantity in bits, rather than - bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. - - - - Declares a type of function which takes an arbitrary -data pointer argument and has no return value. It is -not currently used in GLib or GTK+. - - - - - - - a data pointer - - - - - - Specifies the type of functions passed to g_list_foreach() and -g_slist_foreach(). - - - - - - - the element's data - - - - user data passed to g_list_foreach() or g_slist_foreach() - - - - - - This is the platform dependent conversion specifier for scanning and -printing values of type #gint16. It is a string literal, but doesn't -include the percent-sign, such that you can add precision and length -modifiers between percent-sign and conversion specifier. - -|[<!-- language="C" --> -gint16 in; -gint32 out; -sscanf ("42", "%" G_GINT16_FORMAT, &in) -out = in * 1000; -g_print ("%" G_GINT32_FORMAT, out); -]| - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint16 or #guint16. It -is a string literal, but doesn't include the percent-sign, such -that you can add precision and length modifiers between percent-sign -and conversion specifier and append a conversion specifier. - -The following example prints "0x7b"; -|[<!-- language="C" --> -gint16 value = 123; -g_print ("%#" G_GINT16_MODIFIER "x", value); -]| - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #gint32. See also #G_GINT16_FORMAT. - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint32 or #guint32. It -is a string literal. See also #G_GINT16_MODIFIER. - - - - - This macro is used to insert 64-bit integer literals -into the source code. - - - - a literal integer value, e.g. 0x1d636b02300a7aa7 - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #gint64. See also #G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint64 or #guint64. -It is a string literal. - -Some platforms do not support printing 64-bit integers, even -though the types are supported. On such platforms %G_GINT64_MODIFIER -is not defined. - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #gintptr. - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gintptr or #guintptr. -It is a string literal. - - - - - Expands to the GNU C `alloc_size` function attribute if the compiler -is a new enough gcc. This attribute tells the compiler that the -function returns a pointer to memory of a size that is specified -by the @xth function parameter. - -Place the attribute after the function declaration, just before the -semicolon. - -|[<!-- language="C" --> -gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1); -]| - -See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. - - - - the index of the argument specifying the allocation size - - - - - Expands to the GNU C `alloc_size` function attribute if the compiler is a -new enough gcc. This attribute tells the compiler that the function returns -a pointer to memory of a size that is specified by the product of two -function parameters. - -Place the attribute after the function declaration, just before the -semicolon. - -|[<!-- language="C" --> -gpointer g_malloc_n (gsize n_blocks, - gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2); -]| - -See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. - - - - the index of the argument specifying one factor of the allocation size - - - the index of the argument specifying the second factor of the allocation size - - - - - Expands to a check for a compiler with __GNUC__ defined and a version -greater than or equal to the major and minor numbers provided. For example, -the following would only match on compilers such as GCC 4.8 or newer. - -|[<!-- language="C" --> -#if G_GNUC_CHECK_VERSION(4, 8) -#endif -]| - - - - major version to check against - - - minor version to check against - - - - - Like %G_GNUC_DEPRECATED, but names the intended replacement for the -deprecated symbol if the version of gcc in use is new enough to support -custom deprecation messages. - -Place the attribute after the declaration, just before the semicolon. - -|[<!-- language="C" --> -int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement); -]| - -See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details. - -Note that if @f is a macro, it will be expanded in the warning message. -You can enclose it in quotes to prevent this. (The quotes will show up -in the warning, but it's better than showing the macro expansion.) - - - - the intended replacement for the deprecated symbol, - such as the name of a function - - - - - Expands to the GNU C `format_arg` function attribute if the compiler -is gcc. This function attribute specifies that a function takes a -format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style -function and modifies it, so that the result can be passed to a `printf()`, -`scanf()`, `strftime()` or `strfmon()` style function (with the remaining -arguments to the format function the same as they would have been -for the unmodified string). - -Place the attribute after the function declaration, just before the -semicolon. - -See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details. - -|[<!-- language="C" --> -gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); -]| - - - - the index of the argument - - - - - Expands to "" on all modern compilers, and to __FUNCTION__ on gcc -version 2.x. Don't use it. - Use G_STRFUNC() instead - - - - - Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ -on gcc version 2.x. Don't use it. - Use G_STRFUNC() instead - - - - - Expands to the GNU C `format` function attribute if the compiler is gcc. -This is used for declaring functions which take a variable number of -arguments, with the same syntax as `printf()`. It allows the compiler -to type-check the arguments passed to the function. - -Place the attribute after the function declaration, just before the -semicolon. - -See the -[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) -for more details. - -|[<!-- language="C" --> -gint g_snprintf (gchar *string, - gulong n, - gchar const *format, - ...) G_GNUC_PRINTF (3, 4); -]| - - - - the index of the argument corresponding to the - format string (the arguments are numbered from 1) - - - the index of the first of the format arguments, or 0 if - there are no format arguments - - - - - Expands to the GNU C `format` function attribute if the compiler is gcc. -This is used for declaring functions which take a variable number of -arguments, with the same syntax as `scanf()`. It allows the compiler -to type-check the arguments passed to the function. - -|[<!-- language="C" --> -int my_scanf (MyStream *stream, - const char *format, - ...) G_GNUC_SCANF (2, 3); -int my_vscanf (MyStream *stream, - const char *format, - va_list ap) G_GNUC_SCANF (2, 0); -]| - -See the -[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) -for details. - - - - the index of the argument corresponding to - the format string (the arguments are numbered from 1) - - - the index of the first of the format arguments, or 0 if - there are no format arguments - - - - - Expands to the GNU C `strftime` format function attribute if the compiler -is gcc. This is used for declaring functions which take a format argument -which is passed to `strftime()` or an API implementing its formats. It allows -the compiler check the format passed to the function. - -|[<!-- language="C" --> -gsize my_strftime (MyBuffer *buffer, - const char *format, - const struct tm *tm) G_GNUC_STRFTIME (2); -]| - -See the -[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) -for details. - - - - the index of the argument corresponding to - the format string (the arguments are numbered from 1) - - - - - This macro is used to insert #goffset 64-bit integer literals -into the source code. - -See also #G_GINT64_CONSTANT. - - - - a literal integer value, e.g. 0x1d636b02300a7aa7 - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #gsize. See also #G_GINT16_FORMAT. - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gsize. It -is a string literal. - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #gssize. See also #G_GINT16_FORMAT. - - - - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gssize. It -is a string literal. - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #guint16. See also #G_GINT16_FORMAT - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #guint32. See also #G_GINT16_FORMAT. - - - - - This macro is used to insert 64-bit unsigned integer -literals into the source code. - - - - a literal integer value, e.g. 0x1d636b02300a7aa7U - - - - - This is the platform dependent conversion specifier for scanning -and printing values of type #guint64. See also #G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GUINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - - - - - This is the platform dependent conversion specifier -for scanning and printing values of type #guintptr. - - - - - - - - - - - - - Defined to 1 if gcc-style visibility handling is supported. - - - - - - - - - - - - - Specifies the type of the function passed to g_hash_table_foreach(). -It is called with each key/value pair, together with the @user_data -parameter which is passed to g_hash_table_foreach(). - - - - - - - a key - - - - the value corresponding to the key - - - - user data passed to g_hash_table_foreach() - - - - - - Casts a pointer to a `GHook*`. - - - - a pointer - - - - - Returns %TRUE if the #GHook is active, which is normally the case -until the #GHook is destroyed. - - - - a #GHook - - - - - Gets the flags of a hook. - - - - a #GHook - - - - - The position of the first bit which is not reserved for internal -use be the #GHook implementation, i.e. -`1 << G_HOOK_FLAG_USER_SHIFT` is the first -bit which can be used for application-defined flags. - - - - - Returns %TRUE if the #GHook function is currently executing. - - - - a #GHook - - - - - Returns %TRUE if the #GHook is not in a #GHookList. - - - - a #GHook - - - - - Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, -it is active and it has not been destroyed. - - - - a #GHook - - - - - Specifies the type of the function passed to -g_hash_table_foreach_remove(). It is called with each key/value -pair, together with the @user_data parameter passed to -g_hash_table_foreach_remove(). It should return %TRUE if the -key/value pair should be removed from the #GHashTable. - - - %TRUE if the key/value pair should be removed from the - #GHashTable - - - - - a key - - - - the value associated with the key - - - - user data passed to g_hash_table_remove() - - - - - - Specifies the type of the hash function which is passed to -g_hash_table_new() when a #GHashTable is created. - -The function is passed a key and should return a #guint hash value. -The functions g_direct_hash(), g_int_hash() and g_str_hash() provide -hash functions which can be used when the key is a #gpointer, #gint*, -and #gchar* respectively. - -g_direct_hash() is also the appropriate hash function for keys -of the form `GINT_TO_POINTER (n)` (or similar macros). - -A good hash functions should produce -hash values that are evenly distributed over a fairly large range. -The modulus is taken with the hash table size (a prime number) to -find the 'bucket' to place each key into. The function should also -be very fast, since it is called for each key lookup. - -Note that the hash functions provided by GLib have these qualities, -but are not particularly robust against manufactured keys that -cause hash collisions. Therefore, you should consider choosing -a more secure hash function when using a GHashTable with keys -that originate in untrusted data (such as HTTP requests). -Using g_str_hash() in that situation might make your application -vulerable to -[Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). - -The key to choosing a good hash is unpredictability. Even -cryptographic hashes are very easy to find collisions for when the -remainder is taken modulo a somewhat predictable prime number. There -must be an element of randomness that an attacker is unable to guess. - - - the hash value corresponding to the key - - - - - a key - - - - - - The #GHashTable struct is an opaque data structure to represent a -[Hash Table][glib-Hash-Tables]. It should only be accessed via the -following functions. - - - This is a convenience function for using a #GHashTable as a set. It -is equivalent to calling g_hash_table_replace() with @key as both the -key and the value. - -In particular, this means that if @key already exists in the hash table, then -the old copy of @key in the hash table is freed and @key replaces it in the -table. - -When a hash table only ever contains keys that have themselves as the -corresponding value it is able to be stored more efficiently. See -the discussion in the section description. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - - - Checks if @key is in @hash_table. - - - %TRUE if @key is in @hash_table, %FALSE otherwise. - - - - - a #GHashTable - - - - - - - a key to check - - - - - - Destroys all keys and values in the #GHashTable and decrements its -reference count by 1. If keys and/or values are dynamically allocated, -you should either free them first or create the #GHashTable with destroy -notifiers using g_hash_table_new_full(). In the latter case the destroy -functions you supplied will be called on all keys and values during the -destruction phase. - - - - - - - a #GHashTable - - - - - - - - - Calls the given function for key/value pairs in the #GHashTable -until @predicate returns %TRUE. The function is passed the key -and value of each pair, and the given @user_data parameter. The -hash table may not be modified while iterating over it (you can't -add/remove items). - -Note, that hash tables are really only optimized for forward -lookups, i.e. g_hash_table_lookup(). So code that frequently issues -g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of -once per every entry in a hash table) should probably be reworked -to use additional or different data structures for reverse lookups -(keep in mind that an O(n) find/foreach operation issued for all n -values in a hash table ends up needing O(n*n) operations). - - - The value of the first key/value pair is returned, - for which @predicate evaluates to %TRUE. If no pair with the - requested property is found, %NULL is returned. - - - - - a #GHashTable - - - - - - - function to test the key/value pairs for a certain property - - - - user data to pass to the function - - - - - - Calls the given function for each of the key/value pairs in the -#GHashTable. The function is passed the key and value of each -pair, and the given @user_data parameter. The hash table may not -be modified while iterating over it (you can't add/remove -items). To remove all items matching a predicate, use -g_hash_table_foreach_remove(). - -The order in which g_hash_table_foreach() iterates over the keys/values in -the hash table is not defined. - -See g_hash_table_find() for performance caveats for linear -order searches in contrast to g_hash_table_lookup(). - - - - - - - a #GHashTable - - - - - - - the function to call for each key/value pair - - - - user data to pass to the function - - - - - - Calls the given function for each key/value pair in the -#GHashTable. If the function returns %TRUE, then the key/value -pair is removed from the #GHashTable. If you supplied key or -value destroy functions when creating the #GHashTable, they are -used to free the memory allocated for the removed keys and values. - -See #GHashTableIter for an alternative way to loop over the -key/value pairs in the hash table. - - - the number of key/value pairs removed - - - - - a #GHashTable - - - - - - - the function to call for each key/value pair - - - - user data to pass to the function - - - - - - Calls the given function for each key/value pair in the -#GHashTable. If the function returns %TRUE, then the key/value -pair is removed from the #GHashTable, but no key or value -destroy functions are called. - -See #GHashTableIter for an alternative way to loop over the -key/value pairs in the hash table. - - - the number of key/value pairs removed. - - - - - a #GHashTable - - - - - - - the function to call for each key/value pair - - - - user data to pass to the function - - - - - - Retrieves every key inside @hash_table. The returned data is valid -until changes to the hash release those keys. - -This iterates over every entry in the hash table to build its return value. -To iterate over the entries in a #GHashTable more efficiently, use a -#GHashTableIter. - - - a #GList containing all the keys - inside the hash table. The content of the list is owned by the - hash table and should not be modified or freed. Use g_list_free() - when done using the list. - - - - - - - a #GHashTable - - - - - - - - - Retrieves every key inside @hash_table, as an array. - -The returned array is %NULL-terminated but may contain %NULL as a -key. Use @length to determine the true length if it's possible that -%NULL was used as the value for a key. - -Note: in the common case of a string-keyed #GHashTable, the return -value of this function can be conveniently cast to (const gchar **). - -This iterates over every entry in the hash table to build its return value. -To iterate over the entries in a #GHashTable more efficiently, use a -#GHashTableIter. - -You should always free the return result with g_free(). In the -above-mentioned case of a string-keyed hash table, it may be -appropriate to use g_strfreev() if you call g_hash_table_steal_all() -first to transfer ownership of the keys. - - - a - %NULL-terminated array containing each key from the table. - - - - - - - a #GHashTable - - - - - - - the length of the returned array - - - - - - Retrieves every value inside @hash_table. The returned data -is valid until @hash_table is modified. - -This iterates over every entry in the hash table to build its return value. -To iterate over the entries in a #GHashTable more efficiently, use a -#GHashTableIter. - - - a #GList containing all the values - inside the hash table. The content of the list is owned by the - hash table and should not be modified or freed. Use g_list_free() - when done using the list. - - - - - - - a #GHashTable - - - - - - - - - Inserts a new key and value into a #GHashTable. - -If the key already exists in the #GHashTable its current -value is replaced with the new value. If you supplied a -@value_destroy_func when creating the #GHashTable, the old -value is freed using that function. If you supplied a -@key_destroy_func when creating the #GHashTable, the passed -key is freed using that function. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - the value to associate with the key - - - - - - Looks up a key in a #GHashTable. Note that this function cannot -distinguish between a key that is not present and one which is present -and has the value %NULL. If you need this distinction, use -g_hash_table_lookup_extended(). - - - the associated value, or %NULL if the key is not found - - - - - a #GHashTable - - - - - - - the key to look up - - - - - - Looks up a key in the #GHashTable, returning the original key and the -associated value and a #gboolean which is %TRUE if the key was found. This -is useful if you need to free the memory allocated for the original key, -for example before calling g_hash_table_remove(). - -You can actually pass %NULL for @lookup_key to test -whether the %NULL key exists, provided the hash and equal functions -of @hash_table are %NULL-safe. - - - %TRUE if the key was found in the #GHashTable - - - - - a #GHashTable - - - - - - - the key to look up - - - - return location for the original key - - - - return location for the value associated -with the key - - - - - - Creates a new #GHashTable with a reference count of 1. - -Hash values returned by @hash_func are used to determine where keys -are stored within the #GHashTable data structure. The g_direct_hash(), -g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() -functions are provided for some common types of keys. -If @hash_func is %NULL, g_direct_hash() is used. - -@key_equal_func is used when looking up keys in the #GHashTable. -The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() -and g_str_equal() functions are provided for the most common types -of keys. If @key_equal_func is %NULL, keys are compared directly in -a similar fashion to g_direct_equal(), but without the overhead of -a function call. @key_equal_func is called with the key from the hash table -as its first parameter, and the user-provided key to check against as -its second. - - - a new #GHashTable - - - - - - - - a function to create a hash value from a key - - - - a function to check two keys for equality - - - - - - Creates a new #GHashTable like g_hash_table_new() with a reference -count of 1 and allows to specify functions to free the memory -allocated for the key and value that get called when removing the -entry from the #GHashTable. - -Since version 2.42 it is permissible for destroy notify functions to -recursively remove further items from the hash table. This is only -permissible if the application still holds a reference to the hash table. -This means that you may need to ensure that the hash table is empty by -calling g_hash_table_remove_all() before releasing the last reference using -g_hash_table_unref(). - - - a new #GHashTable - - - - - - - - a function to create a hash value from a key - - - - a function to check two keys for equality - - - - a function to free the memory allocated for the key - used when removing the entry from the #GHashTable, or %NULL - if you don't want to supply such a function. - - - - a function to free the memory allocated for the - value used when removing the entry from the #GHashTable, or %NULL - if you don't want to supply such a function. - - - - - - Atomically increments the reference count of @hash_table by one. -This function is MT-safe and may be called from any thread. - - - the passed in #GHashTable - - - - - - - - a valid #GHashTable - - - - - - - - - Removes a key and its associated value from a #GHashTable. - -If the #GHashTable was created using g_hash_table_new_full(), the -key and value are freed using the supplied destroy functions, otherwise -you have to make sure that any dynamically allocated values are freed -yourself. - - - %TRUE if the key was found and removed from the #GHashTable - - - - - a #GHashTable - - - - - - - the key to remove - - - - - - Removes all keys and their associated values from a #GHashTable. - -If the #GHashTable was created using g_hash_table_new_full(), -the keys and values are freed using the supplied destroy functions, -otherwise you have to make sure that any dynamically allocated -values are freed yourself. - - - - - - - a #GHashTable - - - - - - - - - Inserts a new key and value into a #GHashTable similar to -g_hash_table_insert(). The difference is that if the key -already exists in the #GHashTable, it gets replaced by the -new key. If you supplied a @value_destroy_func when creating -the #GHashTable, the old value is freed using that function. -If you supplied a @key_destroy_func when creating the -#GHashTable, the old key is freed using that function. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - the value to associate with the key - - - - - - Returns the number of elements contained in the #GHashTable. - - - the number of key/value pairs in the #GHashTable. - - - - - a #GHashTable - - - - - - - - - Removes a key and its associated value from a #GHashTable without -calling the key and value destroy functions. - - - %TRUE if the key was found and removed from the #GHashTable - - - - - a #GHashTable - - - - - - - the key to remove - - - - - - Removes all keys and their associated values from a #GHashTable -without calling the key and value destroy functions. - - - - - - - a #GHashTable - - - - - - - - - Looks up a key in the #GHashTable, stealing the original key and the -associated value and returning %TRUE if the key was found. If the key was -not found, %FALSE is returned. - -If found, the stolen key and value are removed from the hash table without -calling the key and value destroy functions, and ownership is transferred to -the caller of this method; as with g_hash_table_steal(). - -You can pass %NULL for @lookup_key, provided the hash and equal functions -of @hash_table are %NULL-safe. - - - %TRUE if the key was found in the #GHashTable - - - - - a #GHashTable - - - - - - - the key to look up - - - - return location for the - original key - - - - return location - for the value associated with the key - - - - - - Atomically decrements the reference count of @hash_table by one. -If the reference count drops to 0, all keys and values will be -destroyed, and all memory allocated by the hash table is released. -This function is MT-safe and may be called from any thread. - - - - - - - a valid #GHashTable - - - - - - - - - - A GHashTableIter structure represents an iterator that can be used -to iterate over the elements of a #GHashTable. GHashTableIter -structures are typically allocated on the stack and then initialized -with g_hash_table_iter_init(). - -The iteration order of a #GHashTableIter over the keys/values in a hash -table is not defined. - - - - - - - - - - - - - - - - - - - - - Returns the #GHashTable associated with @iter. - - - the #GHashTable associated with @iter. - - - - - - - - an initialized #GHashTableIter - - - - - - Initializes a key/value pair iterator and associates it with -@hash_table. Modifying the hash table after calling this function -invalidates the returned iterator. - -The iteration order of a #GHashTableIter over the keys/values in a hash -table is not defined. - -|[<!-- language="C" --> -GHashTableIter iter; -gpointer key, value; - -g_hash_table_iter_init (&iter, hash_table); -while (g_hash_table_iter_next (&iter, &key, &value)) - { - // do something with key and value - } -]| - - - - - - - an uninitialized #GHashTableIter - - - - a #GHashTable - - - - - - - - - Advances @iter and retrieves the key and/or value that are now -pointed to as a result of this advancement. If %FALSE is returned, -@key and @value are not set, and the iterator becomes invalid. - - - %FALSE if the end of the #GHashTable has been reached. - - - - - an initialized #GHashTableIter - - - - a location to store the key - - - - a location to store the value - - - - - - Removes the key/value pair currently pointed to by the iterator -from its associated #GHashTable. Can only be called after -g_hash_table_iter_next() returned %TRUE, and cannot be called -more than once for the same key/value pair. - -If the #GHashTable was created using g_hash_table_new_full(), -the key and value are freed using the supplied destroy functions, -otherwise you have to make sure that any dynamically allocated -values are freed yourself. - -It is safe to continue iterating the #GHashTable afterward: -|[<!-- language="C" --> -while (g_hash_table_iter_next (&iter, &key, &value)) - { - if (condition) - g_hash_table_iter_remove (&iter); - } -]| - - - - - - - an initialized #GHashTableIter - - - - - - Replaces the value currently pointed to by the iterator -from its associated #GHashTable. Can only be called after -g_hash_table_iter_next() returned %TRUE. - -If you supplied a @value_destroy_func when creating the -#GHashTable, the old value is freed using that function. - - - - - - - an initialized #GHashTableIter - - - - the value to replace with - - - - - - Removes the key/value pair currently pointed to by the -iterator from its associated #GHashTable, without calling -the key and value destroy functions. Can only be called -after g_hash_table_iter_next() returned %TRUE, and cannot -be called more than once for the same key/value pair. - - - - - - - an initialized #GHashTableIter - - - - - - - An opaque structure representing a HMAC operation. -To create a new GHmac, use g_hmac_new(). To free -a GHmac, use g_hmac_unref(). - - - Copies a #GHmac. If @hmac has been closed, by calling -g_hmac_get_string() or g_hmac_get_digest(), the copied -HMAC will be closed as well. - - - the copy of the passed #GHmac. Use g_hmac_unref() - when finished using it. - - - - - the #GHmac to copy - - - - - - Gets the digest from @checksum as a raw binary array and places it -into @buffer. The size of the digest depends on the type of checksum. - -Once this function has been called, the #GHmac is closed and can -no longer be updated with g_checksum_update(). - - - - - - - a #GHmac - - - - output buffer - - - - - - an inout parameter. The caller initializes it to the - size of @buffer. After the call it contains the length of the digest - - - - - - Gets the HMAC as a hexadecimal string. - -Once this function has been called the #GHmac can no longer be -updated with g_hmac_update(). - -The hexadecimal characters will be lower case. - - - the hexadecimal representation of the HMAC. The - returned string is owned by the HMAC and should not be modified - or freed. - - - - - a #GHmac - - - - - - Atomically increments the reference count of @hmac by one. - -This function is MT-safe and may be called from any thread. - - - the passed in #GHmac. - - - - - a valid #GHmac - - - - - - Atomically decrements the reference count of @hmac by one. - -If the reference count drops to 0, all keys and values will be -destroyed, and all memory allocated by the hash table is released. -This function is MT-safe and may be called from any thread. -Frees the memory allocated for @hmac. - - - - - - - a #GHmac - - - - - - Feeds @data into an existing #GHmac. - -The HMAC must still be open, that is g_hmac_get_string() or -g_hmac_get_digest() must not have been called on @hmac. - - - - - - - a #GHmac - - - - buffer used to compute the checksum - - - - - - size of the buffer, or -1 if it is a nul-terminated string - - - - - - Creates a new #GHmac, using the digest algorithm @digest_type. -If the @digest_type is not known, %NULL is returned. -A #GHmac can be used to compute the HMAC of a key and an -arbitrary binary blob, using different hashing algorithms. - -A #GHmac works by feeding a binary blob through g_hmac_update() -until the data is complete; the digest can then be extracted -using g_hmac_get_string(), which will return the checksum as a -hexadecimal string; or g_hmac_get_digest(), which will return a -array of raw bytes. Once either g_hmac_get_string() or -g_hmac_get_digest() have been called on a #GHmac, the HMAC -will be closed and it won't be possible to call g_hmac_update() -on it anymore. - -Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. -Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. - - - the newly created #GHmac, or %NULL. - Use g_hmac_unref() to free the memory allocated by it. - - - - - the desired type of digest - - - - the key for the HMAC - - - - - - the length of the keys - - - - - - - The #GHook struct represents a single hook function in a #GHookList. - - - data which is passed to func when this hook is invoked - - - - pointer to the next hook in the list - - - - pointer to the previous hook in the list - - - - the reference count of this hook - - - - the id of this hook, which is unique within its list - - - - flags which are set for this hook. See #GHookFlagMask for - predefined flags - - - - the function to call when this hook is invoked. The possible - signatures for this function are #GHookFunc and #GHookCheckFunc - - - - the default @finalize_hook function of a #GHookList calls - this member of the hook that is being finalized - - - - Compares the ids of two #GHook elements, returning a negative value -if the second id is greater than the first. - - - a value <= 0 if the id of @sibling is >= the id of @new_hook - - - - - a #GHook - - - - a #GHook to compare with @new_hook - - - - - - Allocates space for a #GHook and initializes it. - - - a new #GHook - - - - - a #GHookList - - - - - - Destroys a #GHook, given its ID. - - - %TRUE if the #GHook was found in the #GHookList and destroyed - - - - - a #GHookList - - - - a hook ID - - - - - - Removes one #GHook from a #GHookList, marking it -inactive and calling g_hook_unref() on it. - - - - - - - a #GHookList - - - - the #GHook to remove - - - - - - Finds a #GHook in a #GHookList using the given function to -test for a match. - - - the found #GHook or %NULL if no matching #GHook is found - - - - - a #GHookList - - - - %TRUE if #GHook elements which have been destroyed - should be skipped - - - - the function to call for each #GHook, which should return - %TRUE when the #GHook has been found - - - - the data to pass to @func - - - - - - Finds a #GHook in a #GHookList with the given data. - - - the #GHook with the given @data or %NULL if no matching - #GHook is found - - - - - a #GHookList - - - - %TRUE if #GHook elements which have been destroyed - should be skipped - - - - the data to find - - - - - - Finds a #GHook in a #GHookList with the given function. - - - the #GHook with the given @func or %NULL if no matching - #GHook is found - - - - - a #GHookList - - - - %TRUE if #GHook elements which have been destroyed - should be skipped - - - - the function to find - - - - - - Finds a #GHook in a #GHookList with the given function and data. - - - the #GHook with the given @func and @data or %NULL if - no matching #GHook is found - - - - - a #GHookList - - - - %TRUE if #GHook elements which have been destroyed - should be skipped - - - - the function to find - - - - the data to find - - - - - - Returns the first #GHook in a #GHookList which has not been destroyed. -The reference count for the #GHook is incremented, so you must call -g_hook_unref() to restore it when no longer needed. (Or call -g_hook_next_valid() if you are stepping through the #GHookList.) - - - the first valid #GHook, or %NULL if none are valid - - - - - a #GHookList - - - - %TRUE if hooks which are currently running - (e.g. in another thread) are considered valid. If set to %FALSE, - these are skipped - - - - - - Calls the #GHookList @finalize_hook function if it exists, -and frees the memory allocated for the #GHook. - - - - - - - a #GHookList - - - - the #GHook to free - - - - - - Returns the #GHook with the given id, or %NULL if it is not found. - - - the #GHook with the given id, or %NULL if it is not found - - - - - a #GHookList - - - - a hook id - - - - - - Inserts a #GHook into a #GHookList, before a given #GHook. - - - - - - - a #GHookList - - - - the #GHook to insert the new #GHook before - - - - the #GHook to insert - - - - - - Inserts a #GHook into a #GHookList, sorted by the given function. - - - - - - - a #GHookList - - - - the #GHook to insert - - - - the comparison function used to sort the #GHook elements - - - - - - Returns the next #GHook in a #GHookList which has not been destroyed. -The reference count for the #GHook is incremented, so you must call -g_hook_unref() to restore it when no longer needed. (Or continue to call -g_hook_next_valid() until %NULL is returned.) - - - the next valid #GHook, or %NULL if none are valid - - - - - a #GHookList - - - - the current #GHook - - - - %TRUE if hooks which are currently running - (e.g. in another thread) are considered valid. If set to %FALSE, - these are skipped - - - - - - Prepends a #GHook on the start of a #GHookList. - - - - - - - a #GHookList - - - - the #GHook to add to the start of @hook_list - - - - - - Increments the reference count for a #GHook. - - - the @hook that was passed in (since 2.6) - - - - - a #GHookList - - - - the #GHook to increment the reference count of - - - - - - Decrements the reference count of a #GHook. -If the reference count falls to 0, the #GHook is removed -from the #GHookList and g_hook_free() is called to free it. - - - - - - - a #GHookList - - - - the #GHook to unref - - - - - - - Defines the type of a hook function that can be invoked -by g_hook_list_invoke_check(). - - - %FALSE if the #GHook should be destroyed - - - - - the data field of the #GHook is passed to the hook function here - - - - - - Defines the type of function used by g_hook_list_marshal_check(). - - - %FALSE if @hook should be destroyed - - - - - a #GHook - - - - user data - - - - - - Defines the type of function used to compare #GHook elements in -g_hook_insert_sorted(). - - - a value <= 0 if @new_hook should be before @sibling - - - - - the #GHook being inserted - - - - the #GHook to compare with @new_hook - - - - - - Defines the type of function to be called when a hook in a -list of hooks gets finalized. - - - - - - - a #GHookList - - - - the hook in @hook_list that gets finalized - - - - - - Defines the type of the function passed to g_hook_find(). - - - %TRUE if the required #GHook has been found - - - - - a #GHook - - - - user data passed to g_hook_find_func() - - - - - - Flags used internally in the #GHook implementation. - - - set if the hook has not been destroyed - - - set if the hook is currently being run - - - A mask covering all bits reserved for - hook flags; see %G_HOOK_FLAG_USER_SHIFT - - - - Defines the type of a hook function that can be invoked -by g_hook_list_invoke(). - - - - - - - the data field of the #GHook is passed to the hook function here - - - - - - The #GHookList struct represents a list of hook functions. - - - the next free #GHook id - - - - the size of the #GHookList elements, in bytes - - - - 1 if the #GHookList has been initialized - - - - the first #GHook element in the list - - - - unused - - - - the function to call to finalize a #GHook element. - The default behaviour is to call the hooks @destroy function - - - - unused - - - - - - Removes all the #GHook elements from a #GHookList. - - - - - - - a #GHookList - - - - - - Initializes a #GHookList. -This must be called before the #GHookList is used. - - - - - - - a #GHookList - - - - the size of each element in the #GHookList, - typically `sizeof (GHook)`. - - - - - - Calls all of the #GHook functions in a #GHookList. - - - - - - - a #GHookList - - - - %TRUE if functions which are already running - (e.g. in another thread) can be called. If set to %FALSE, - these are skipped - - - - - - Calls all of the #GHook functions in a #GHookList. -Any function which returns %FALSE is removed from the #GHookList. - - - - - - - a #GHookList - - - - %TRUE if functions which are already running - (e.g. in another thread) can be called. If set to %FALSE, - these are skipped - - - - - - Calls a function on each valid #GHook. - - - - - - - a #GHookList - - - - %TRUE if hooks which are currently running - (e.g. in another thread) are considered valid. If set to %FALSE, - these are skipped - - - - the function to call for each #GHook - - - - data to pass to @marshaller - - - - - - Calls a function on each valid #GHook and destroys it if the -function returns %FALSE. - - - - - - - a #GHookList - - - - %TRUE if hooks which are currently running - (e.g. in another thread) are considered valid. If set to %FALSE, - these are skipped - - - - the function to call for each #GHook - - - - data to pass to @marshaller - - - - - - - Defines the type of function used by g_hook_list_marshal(). - - - - - - - a #GHook - - - - user data - - - - - - The GIConv struct wraps an iconv() conversion descriptor. It contains -private data and should only be accessed using the following functions. - - - Same as the standard UNIX routine iconv(), but -may be implemented via libiconv on UNIX flavors that lack -a native implementation. - -GLib provides g_convert() and g_locale_to_utf8() which are likely -more convenient than the raw iconv wrappers. - -Note that the behaviour of iconv() for characters which are valid in the -input character set, but which have no representation in the output character -set, is implementation defined. This function may return success (with a -positive number of non-reversible conversions as replacement characters were -used), or it may return -1 and set an error such as %EILSEQ, in such a -situation. - - - count of non-reversible conversions, or -1 on error - - - - - conversion descriptor from g_iconv_open() - - - - bytes to convert - - - - inout parameter, bytes remaining to convert in @inbuf - - - - converted output bytes - - - - inout parameter, bytes available to fill in @outbuf - - - - - - Same as the standard UNIX routine iconv_close(), but -may be implemented via libiconv on UNIX flavors that lack -a native implementation. Should be called to clean up -the conversion descriptor from g_iconv_open() when -you are done converting things. - -GLib provides g_convert() and g_locale_to_utf8() which are likely -more convenient than the raw iconv wrappers. - - - -1 on error, 0 on success - - - - - a conversion descriptor from g_iconv_open() - - - - - - Same as the standard UNIX routine iconv_open(), but -may be implemented via libiconv on UNIX flavors that lack -a native implementation. - -GLib provides g_convert() and g_locale_to_utf8() which are likely -more convenient than the raw iconv wrappers. - - - a "conversion descriptor", or (GIConv)-1 if - opening the converter failed. - - - - - destination codeset - - - - source codeset - - - - - - - The bias by which exponents in double-precision floats are offset. - - - - - The bias by which exponents in single-precision floats are offset. - - - - - A data structure representing an IO Channel. The fields should be -considered private and should only be accessed with the following -functions. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Open a file @filename as a #GIOChannel using mode @mode. This -channel will be closed when the last reference to it is dropped, -so there is no need to call g_io_channel_close() (though doing -so will not cause problems, as long as no attempt is made to -access the channel after it is closed). - - - A #GIOChannel on success, %NULL on failure. - - - - - A string containing the name of a file - - - - One of "r", "w", "a", "r+", "w+", "a+". These have - the same meaning as in fopen() - - - - - - Creates a new #GIOChannel given a file descriptor. On UNIX systems -this works for plain files, pipes, and sockets. - -The returned #GIOChannel has a reference count of 1. - -The default encoding for #GIOChannel is UTF-8. If your application -is reading output from a command using via pipe, you may need to set -the encoding to the encoding of the current locale (see -g_get_charset()) with the g_io_channel_set_encoding() function. -By default, the fd passed will not be closed when the final reference -to the #GIOChannel data structure is dropped. - -If you want to read raw binary data without interpretation, then -call the g_io_channel_set_encoding() function with %NULL for the -encoding argument. - -This function is available in GLib on Windows, too, but you should -avoid using it on Windows. The domain of file descriptors and -sockets overlap. There is no way for GLib to know which one you mean -in case the argument you pass to this function happens to be both a -valid file descriptor and socket. If that happens a warning is -issued, and GLib assumes that it is the file descriptor you mean. - - - a new #GIOChannel. - - - - - a file descriptor. - - - - - - Close an IO channel. Any pending data to be written will be -flushed, ignoring errors. The channel will not be freed until the -last reference is dropped using g_io_channel_unref(). - Use g_io_channel_shutdown() instead. - - - - - - - A #GIOChannel - - - - - - Flushes the write buffer for the GIOChannel. - - - the status of the operation: One of - #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or - #G_IO_STATUS_ERROR. - - - - - a #GIOChannel - - - - - - This function returns a #GIOCondition depending on whether there -is data to be read/space to write data in the internal buffers in -the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. - - - A #GIOCondition - - - - - A #GIOChannel - - - - - - Gets the buffer size. - - - the size of the buffer. - - - - - a #GIOChannel - - - - - - Returns whether @channel is buffered. - - - %TRUE if the @channel is buffered. - - - - - a #GIOChannel - - - - - - Returns whether the file/socket/whatever associated with @channel -will be closed when @channel receives its final unref and is -destroyed. The default value of this is %TRUE for channels created -by g_io_channel_new_file (), and %FALSE for all other channels. - - - %TRUE if the channel will be closed, %FALSE otherwise. - - - - - a #GIOChannel. - - - - - - Gets the encoding for the input/output of the channel. -The internal encoding is always UTF-8. The encoding %NULL -makes the channel safe for binary data. - - - A string containing the encoding, this string is - owned by GLib and must not be freed. - - - - - a #GIOChannel - - - - - - Gets the current flags for a #GIOChannel, including read-only -flags such as %G_IO_FLAG_IS_READABLE. - -The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE -are cached for internal use by the channel when it is created. -If they should change at some later point (e.g. partial shutdown -of a socket with the UNIX shutdown() function), the user -should immediately call g_io_channel_get_flags() to update -the internal values of these flags. - - - the flags which are set on the channel - - - - - a #GIOChannel - - - - - - This returns the string that #GIOChannel uses to determine -where in the file a line break occurs. A value of %NULL -indicates autodetection. - - - The line termination string. This value - is owned by GLib and must not be freed. - - - - - a #GIOChannel - - - - a location to return the length of the line terminator - - - - - - Initializes a #GIOChannel struct. - -This is called by each of the above functions when creating a -#GIOChannel, and so is not often needed by the application -programmer (unless you are creating a new type of #GIOChannel). - - - - - - - a #GIOChannel - - - - - - Reads data from a #GIOChannel. - Use g_io_channel_read_chars() instead. - - - %G_IO_ERROR_NONE if the operation was successful. - - - - - a #GIOChannel - - - - a buffer to read the data into (which should be at least - count bytes long) - - - - the number of bytes to read from the #GIOChannel - - - - returns the number of bytes actually read - - - - - - Replacement for g_io_channel_read() with the new API. - - - the status of the operation. - - - - - a #GIOChannel - - - - - a buffer to read data into - - - - - - the size of the buffer. Note that the buffer may not be - complelely filled even if there is data in the buffer if the - remaining data is not a complete character. - - - - The number of bytes read. This may be - zero even on success if count < 6 and the channel's encoding - is non-%NULL. This indicates that the next UTF-8 character is - too wide for the buffer. - - - - - - Reads a line, including the terminating character(s), -from a #GIOChannel into a newly-allocated string. -@str_return will contain allocated memory if the return -is %G_IO_STATUS_NORMAL. - - - the status of the operation. - - - - - a #GIOChannel - - - - The line read from the #GIOChannel, including the - line terminator. This data should be freed with g_free() - when no longer needed. This is a nul-terminated string. - If a @length of zero is returned, this will be %NULL instead. - - - - location to store length of the read data, or %NULL - - - - location to store position of line terminator, or %NULL - - - - - - Reads a line from a #GIOChannel, using a #GString as a buffer. - - - the status of the operation. - - - - - a #GIOChannel - - - - a #GString into which the line will be written. - If @buffer already contains data, the old data will - be overwritten. - - - - location to store position of line terminator, or %NULL - - - - - - Reads all the remaining data from the file. - - - %G_IO_STATUS_NORMAL on success. - This function never returns %G_IO_STATUS_EOF. - - - - - a #GIOChannel - - - - Location to - store a pointer to a string holding the remaining data in the - #GIOChannel. This data should be freed with g_free() when no - longer needed. This data is terminated by an extra nul - character, but there may be other nuls in the intervening data. - - - - - - location to store length of the data - - - - - - Reads a Unicode character from @channel. -This function cannot be called on a channel with %NULL encoding. - - - a #GIOStatus - - - - - a #GIOChannel - - - - a location to return a character - - - - - - Increments the reference count of a #GIOChannel. - - - the @channel that was passed in (since 2.6) - - - - - a #GIOChannel - - - - - - Sets the current position in the #GIOChannel, similar to the standard -library function fseek(). - Use g_io_channel_seek_position() instead. - - - %G_IO_ERROR_NONE if the operation was successful. - - - - - a #GIOChannel - - - - an offset, in bytes, which is added to the position specified - by @type - - - - the position in the file, which can be %G_SEEK_CUR (the current - position), %G_SEEK_SET (the start of the file), or %G_SEEK_END - (the end of the file) - - - - - - Replacement for g_io_channel_seek() with the new API. - - - the status of the operation. - - - - - a #GIOChannel - - - - The offset in bytes from the position specified by @type - - - - a #GSeekType. The type %G_SEEK_CUR is only allowed in those - cases where a call to g_io_channel_set_encoding () - is allowed. See the documentation for - g_io_channel_set_encoding () for details. - - - - - - Sets the buffer size. - - - - - - - a #GIOChannel - - - - the size of the buffer, or 0 to let GLib pick a good size - - - - - - The buffering state can only be set if the channel's encoding -is %NULL. For any other encoding, the channel must be buffered. - -A buffered channel can only be set unbuffered if the channel's -internal buffers have been flushed. Newly created channels or -channels which have returned %G_IO_STATUS_EOF -not require such a flush. For write-only channels, a call to -g_io_channel_flush () is sufficient. For all other channels, -the buffers may be flushed by a call to g_io_channel_seek_position (). -This includes the possibility of seeking with seek type %G_SEEK_CUR -and an offset of zero. Note that this means that socket-based -channels cannot be set unbuffered once they have had data -read from them. - -On unbuffered channels, it is safe to mix read and write -calls from the new and old APIs, if this is necessary for -maintaining old code. - -The default state of the channel is buffered. - - - - - - - a #GIOChannel - - - - whether to set the channel buffered or unbuffered - - - - - - Whether to close the channel on the final unref of the #GIOChannel -data structure. The default value of this is %TRUE for channels -created by g_io_channel_new_file (), and %FALSE for all other channels. - -Setting this flag to %TRUE for a channel you have already closed -can cause problems when the final reference to the #GIOChannel is dropped. - - - - - - - a #GIOChannel - - - - Whether to close the channel on the final unref of - the GIOChannel data structure. - - - - - - Sets the encoding for the input/output of the channel. -The internal encoding is always UTF-8. The default encoding -for the external file is UTF-8. - -The encoding %NULL is safe to use with binary data. - -The encoding can only be set if one of the following conditions -is true: - -- The channel was just created, and has not been written to or read from yet. - -- The channel is write-only. - -- The channel is a file, and the file pointer was just repositioned - by a call to g_io_channel_seek_position(). (This flushes all the - internal buffers.) - -- The current encoding is %NULL or UTF-8. - -- One of the (new API) read functions has just returned %G_IO_STATUS_EOF - (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). - -- One of the functions g_io_channel_read_chars() or - g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or - %G_IO_STATUS_ERROR. This may be useful in the case of - %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. - Returning one of these statuses from g_io_channel_read_line(), - g_io_channel_read_line_string(), or g_io_channel_read_to_end() - does not guarantee that the encoding can be changed. - -Channels which do not meet one of the above conditions cannot call -g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if -they are "seekable", cannot call g_io_channel_write_chars() after -calling one of the API "read" functions. - - - %G_IO_STATUS_NORMAL if the encoding was successfully set - - - - - a #GIOChannel - - - - the encoding type - - - - - - Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). - - - the status of the operation. - - - - - a #GIOChannel - - - - the flags to set on the IO channel - - - - - - This sets the string that #GIOChannel uses to determine -where in the file a line break occurs. - - - - - - - a #GIOChannel - - - - The line termination string. Use %NULL for - autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", - and the Unicode paragraph separator. Autodetection should not be - used for anything other than file-based channels. - - - - The length of the termination string. If -1 is passed, the - string is assumed to be nul-terminated. This option allows - termination strings with embedded nuls. - - - - - - Close an IO channel. Any pending data to be written will be -flushed if @flush is %TRUE. The channel will not be freed until the -last reference is dropped using g_io_channel_unref(). - - - the status of the operation. - - - - - a #GIOChannel - - - - if %TRUE, flush pending - - - - - - Returns the file descriptor of the #GIOChannel. - -On Windows this function returns the file descriptor or socket of -the #GIOChannel. - - - the file descriptor of the #GIOChannel. - - - - - a #GIOChannel, created with g_io_channel_unix_new(). - - - - - - Decrements the reference count of a #GIOChannel. - - - - - - - a #GIOChannel - - - - - - Writes data to a #GIOChannel. - Use g_io_channel_write_chars() instead. - - - %G_IO_ERROR_NONE if the operation was successful. - - - - - a #GIOChannel - - - - the buffer containing the data to write - - - - the number of bytes to write - - - - the number of bytes actually written - - - - - - Replacement for g_io_channel_write() with the new API. - -On seekable channels with encodings other than %NULL or UTF-8, generic -mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () -may only be made on a channel from which data has been read in the -cases described in the documentation for g_io_channel_set_encoding (). - - - the status of the operation. - - - - - a #GIOChannel - - - - a buffer to write data from - - - - - - the size of the buffer. If -1, the buffer - is taken to be a nul-terminated string. - - - - The number of bytes written. This can be nonzero - even if the return value is not %G_IO_STATUS_NORMAL. - If the return value is %G_IO_STATUS_NORMAL and the - channel is blocking, this will always be equal - to @count if @count >= 0. - - - - - - Writes a Unicode character to @channel. -This function cannot be called on a channel with %NULL encoding. - - - a #GIOStatus - - - - - a #GIOChannel - - - - a character - - - - - - Converts an `errno` error number to a #GIOChannelError. - - - a #GIOChannelError error number, e.g. - %G_IO_CHANNEL_ERROR_INVAL. - - - - - an `errno` error number, e.g. `EINVAL` - - - - - - - - - - - - Error codes returned by #GIOChannel operations. - - - File too large. - - - Invalid argument. - - - IO error. - - - File is a directory. - - - No space left on device. - - - No such device or address. - - - Value too large for defined datatype. - - - Broken pipe. - - - Some other error. - - - - A bitwise combination representing a condition to watch for on an -event source. - - There is data to read. - - - Data can be written (without blocking). - - - There is urgent data to read. - - - Error condition. - - - Hung up (the connection has been broken, usually for - pipes and sockets). - - - Invalid request. The file descriptor is not open. - - - - #GIOError is only used by the deprecated functions -g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). - - - no error - - - an EAGAIN error occurred - - - an EINVAL error occurred - - - another error occurred - - - - Specifies properties of a #GIOChannel. Some of the flags can only be -read with g_io_channel_get_flags(), but not changed with -g_io_channel_set_flags(). - - - turns on append mode, corresponds to %O_APPEND - (see the documentation of the UNIX open() syscall) - - - turns on nonblocking mode, corresponds to - %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() - syscall) - - - indicates that the io channel is readable. - This flag cannot be changed. - - - indicates that the io channel is writable. - This flag cannot be changed. - - - a misspelled version of @G_IO_FLAG_IS_WRITABLE - that existed before the spelling was fixed in GLib 2.30. It is kept - here for compatibility reasons. Deprecated since 2.30 - - - indicates that the io channel is seekable, - i.e. that g_io_channel_seek_position() can be used on it. - This flag cannot be changed. - - - the mask that specifies all the valid flags. - - - the mask of the flags that are returned from - g_io_channel_get_flags() - - - the mask of the flags that the user can modify - with g_io_channel_set_flags() - - - - Specifies the type of function passed to g_io_add_watch() or -g_io_add_watch_full(), which is called when the requested condition -on a #GIOChannel is satisfied. - - - the function should return %FALSE if the event source - should be removed - - - - - the #GIOChannel event source - - - - the condition which has been satisfied - - - - user data set in g_io_add_watch() or g_io_add_watch_full() - - - - - - A table of functions used to handle different types of #GIOChannel -in a generic way. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Stati returned by most of the #GIOFuncs functions. - - - An error occurred. - - - Success. - - - End of file. - - - Resource temporarily unavailable. - - - - Checks whether a character is a directory -separator. It returns %TRUE for '/' on UNIX -machines and for '\' or '/' under Windows. - - - - a character - - - - - The name of the main group of a desktop entry file, as defined in the -[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). -Consult the specification for more -details about the meanings of the keys below. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list -giving the available application actions. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list -of strings giving the categories in which the desktop entry -should be shown in a menu. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized -string giving the tooltip for the desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true -if the application is D-Bus activatable. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the command line to execute. It is only valid for desktop -entries with the `Application` type. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized -string giving the generic name of the desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean -stating whether the desktop entry has been deleted by the user. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized -string giving the name of the icon to be displayed for the desktop -entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list -of strings giving the MIME types supported by this desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized -string giving the specific name of the desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of -strings identifying the environments that should not display the -desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean -stating whether the desktop entry should be shown in menus. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of -strings identifying the environments that should display the -desktop entry. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -containing the working directory to run the program in. It is only -valid for desktop entries with the `Application` type. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean -stating whether the application supports the -[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string -identifying the WM class or name hint of a window that the application -will create, which can be used to emulate Startup Notification with -older applications. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean -stating whether the program should be run in a terminal window. -It is only valid for desktop entries with the -`Application` type. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the file name of a binary on disk used to determine if the -program is actually installed. It is only valid for desktop entries -with the `Application` type. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the type of the desktop entry. Usually -#G_KEY_FILE_DESKTOP_TYPE_APPLICATION, -#G_KEY_FILE_DESKTOP_TYPE_LINK, or -#G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the URL to access. It is only valid for desktop entries -with the `Link` type. - - - - - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the version of the Desktop Entry Specification used for -the desktop entry file. - - - - - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop -entries representing applications. - - - - - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop -entries representing directories. - - - - - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop -entries representing links to documents. - - - - - The GKeyFile struct contains only private data -and should not be accessed directly. - - - Creates a new empty #GKeyFile object. Use -g_key_file_load_from_file(), g_key_file_load_from_data(), -g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to -read an existing key file. - - - an empty #GKeyFile. - - - - - Clears all keys and groups from @key_file, and decreases the -reference count by 1. If the reference count reaches zero, -frees the key file and all its allocated memory. - - - - - - - a #GKeyFile - - - - - - Returns the value associated with @key under @group_name as a -boolean. - -If @key cannot be found then %FALSE is returned and @error is set -to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value -associated with @key cannot be interpreted as a boolean then %FALSE -is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - the value associated with the key as a boolean, - or %FALSE if the key was not found or could not be parsed. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - - - Returns the values associated with @key under @group_name as -booleans. - -If @key cannot be found then %NULL is returned and @error is set to -#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as booleans then %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - - the values associated with the key as a list of booleans, or %NULL if the - key was not found or could not be parsed. The returned list of booleans - should be freed with g_free() when no longer needed. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - the number of booleans returned - - - - - - Retrieves a comment above @key from @group_name. -If @key is %NULL then @comment will be read from above -@group_name. If both @key and @group_name are %NULL, then -@comment will be read from above the first group in the file. - -Note that the returned string does not include the '#' comment markers, -but does include any whitespace after them (on each line). It includes -the line breaks between lines, but does not include the final line break. - - - a comment that should be freed with g_free() - - - - - a #GKeyFile - - - - a group name, or %NULL - - - - a key - - - - - - Returns the value associated with @key under @group_name as a -double. If @group_name is %NULL, the start_group is used. - -If @key cannot be found then 0.0 is returned and @error is set to -#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated -with @key cannot be interpreted as a double then 0.0 is returned -and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - the value associated with the key as a double, or - 0.0 if the key was not found or could not be parsed. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - - - Returns the values associated with @key under @group_name as -doubles. - -If @key cannot be found then %NULL is returned and @error is set to -#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as doubles then %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - - the values associated with the key as a list of doubles, or %NULL if the - key was not found or could not be parsed. The returned list of doubles - should be freed with g_free() when no longer needed. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - the number of doubles returned - - - - - - Returns all groups in the key file loaded with @key_file. -The array of returned groups will be %NULL-terminated, so -@length may optionally be %NULL. - - - a newly-allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. - - - - - - - a #GKeyFile - - - - return location for the number of returned groups, or %NULL - - - - - - Returns the value associated with @key under @group_name as a signed -64-bit integer. This is similar to g_key_file_get_integer() but can return -64-bit results without truncation. - - - the value associated with the key as a signed 64-bit integer, or -0 if the key was not found or could not be parsed. - - - - - a non-%NULL #GKeyFile - - - - a non-%NULL group name - - - - a non-%NULL key - - - - - - Returns the value associated with @key under @group_name as an -integer. - -If @key cannot be found then 0 is returned and @error is set to -#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated -with @key cannot be interpreted as an integer, or is out of range -for a #gint, then 0 is returned -and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - the value associated with the key as an integer, or - 0 if the key was not found or could not be parsed. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - - - Returns the values associated with @key under @group_name as -integers. - -If @key cannot be found then %NULL is returned and @error is set to -#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated -with @key cannot be interpreted as integers, or are out of range for -#gint, then %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - - - - the values associated with the key as a list of integers, or %NULL if - the key was not found or could not be parsed. The returned list of - integers should be freed with g_free() when no longer needed. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - the number of integers returned - - - - - - Returns all keys for the group name @group_name. The array of -returned keys will be %NULL-terminated, so @length may -optionally be %NULL. In the event that the @group_name cannot -be found, %NULL is returned and @error is set to -#G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - - - a newly-allocated %NULL-terminated array of strings. - Use g_strfreev() to free it. - - - - - - - a #GKeyFile - - - - a group name - - - - return location for the number of keys returned, or %NULL - - - - - - Returns the actual locale which the result of -g_key_file_get_locale_string() or g_key_file_get_locale_string_list() -came from. - -If calling g_key_file_get_locale_string() or -g_key_file_get_locale_string_list() with exactly the same @key_file, -@group_name, @key and @locale, the result of those functions will -have originally been tagged with the locale that is the result of -this function. - - - the locale from the file, or %NULL if the key was not - found or the entry in the file was was untranslated - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier or %NULL - - - - - - Returns the value associated with @key under @group_name -translated in the given @locale if available. If @locale is -%NULL then the current locale is assumed. - -If @locale is to be non-%NULL, or if the current locale will change over -the lifetime of the #GKeyFile, it must be loaded with -%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. - -If @key cannot be found then %NULL is returned and @error is set -to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated -with @key cannot be interpreted or no suitable translation can -be found then the untranslated value is returned. - - - a newly allocated string or %NULL if the specified - key cannot be found. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier or %NULL - - - - - - Returns the values associated with @key under @group_name -translated in the given @locale if available. If @locale is -%NULL then the current locale is assumed. - -If @locale is to be non-%NULL, or if the current locale will change over -the lifetime of the #GKeyFile, it must be loaded with -%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. - -If @key cannot be found then %NULL is returned and @error is set -to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated -with @key cannot be interpreted or no suitable translations -can be found then the untranslated values are returned. The -returned array is %NULL-terminated, so @length may optionally -be %NULL. - - - a newly allocated %NULL-terminated string array - or %NULL if the key isn't found. The string array should be freed - with g_strfreev(). - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier or %NULL - - - - return location for the number of returned strings or %NULL - - - - - - Returns the name of the start group of the file. - - - The start group of the key file. - - - - - a #GKeyFile - - - - - - Returns the string value associated with @key under @group_name. -Unlike g_key_file_get_value(), this function handles escape sequences -like \s. - -In the event the key cannot be found, %NULL is returned and -@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - - - a newly allocated string or %NULL if the specified - key cannot be found. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - - - Returns the values associated with @key under @group_name. - -In the event the key cannot be found, %NULL is returned and -@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - - - - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - return location for the number of returned strings, or %NULL - - - - - - Returns the value associated with @key under @group_name as an unsigned -64-bit integer. This is similar to g_key_file_get_integer() but can return -large positive results without truncation. - - - the value associated with the key as an unsigned 64-bit integer, -or 0 if the key was not found or could not be parsed. - - - - - a non-%NULL #GKeyFile - - - - a non-%NULL group name - - - - a non-%NULL key - - - - - - Returns the raw value associated with @key under @group_name. -Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. - -In the event the key cannot be found, %NULL is returned and -@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the -event that the @group_name cannot be found, %NULL is returned -and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - - - a newly allocated string or %NULL if the specified - key cannot be found. - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - - - Looks whether the key file has the group @group_name. - - - %TRUE if @group_name is a part of @key_file, %FALSE -otherwise. - - - - - a #GKeyFile - - - - a group name - - - - - - Looks whether the key file has the key @key in the group -@group_name. - -Note that this function does not follow the rules for #GError strictly; -the return value both carries meaning and signals an error. To use -this function, you must pass a #GError pointer in @error, and check -whether it is not %NULL to see if an error occurred. - -Language bindings should use g_key_file_get_value() to test whether -or not a key exists. - - - %TRUE if @key is a part of @group_name, %FALSE otherwise - - - - - a #GKeyFile - - - - a group name - - - - a key name - - - - - - Loads a key file from the data in @bytes into an empty #GKeyFile structure. -If the object cannot be created then %error is set to a #GKeyFileError. - - - %TRUE if a key file could be loaded, %FALSE otherwise - - - - - an empty #GKeyFile struct - - - - a #GBytes - - - - flags from #GKeyFileFlags - - - - - - Loads a key file from memory into an empty #GKeyFile structure. -If the object cannot be created then %error is set to a #GKeyFileError. - - - %TRUE if a key file could be loaded, %FALSE otherwise - - - - - an empty #GKeyFile struct - - - - key file loaded in memory - - - - the length of @data in bytes (or (gsize)-1 if data is nul-terminated) - - - - flags from #GKeyFileFlags - - - - - - This function looks for a key file named @file in the paths -returned from g_get_user_data_dir() and g_get_system_data_dirs(), -loads the file into @key_file and returns the file's full path in -@full_path. If the file could not be loaded then an %error is -set to either a #GFileError or #GKeyFileError. - - - %TRUE if a key file could be loaded, %FALSE othewise - - - - - an empty #GKeyFile struct - - - - a relative path to a filename to open and parse - - - - return location for a string containing the full path - of the file, or %NULL - - - - flags from #GKeyFileFlags - - - - - - This function looks for a key file named @file in the paths -specified in @search_dirs, loads the file into @key_file and -returns the file's full path in @full_path. - -If the file could not be found in any of the @search_dirs, -%G_KEY_FILE_ERROR_NOT_FOUND is returned. If -the file is found but the OS returns an error when opening or reading the -file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a -%G_KEY_FILE_ERROR is returned. - - - %TRUE if a key file could be loaded, %FALSE otherwise - - - - - an empty #GKeyFile struct - - - - a relative path to a filename to open and parse - - - - %NULL-terminated array of directories to search - - - - - - return location for a string containing the full path - of the file, or %NULL - - - - flags from #GKeyFileFlags - - - - - - Loads a key file into an empty #GKeyFile structure. - -If the OS returns an error when opening or reading the file, a -%G_FILE_ERROR is returned. If there is a problem parsing the file, a -%G_KEY_FILE_ERROR is returned. - -This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the -@file is not found, %G_FILE_ERROR_NOENT is returned. - - - %TRUE if a key file could be loaded, %FALSE otherwise - - - - - an empty #GKeyFile struct - - - - the path of a filename to load, in the GLib filename encoding - - - - flags from #GKeyFileFlags - - - - - - Increases the reference count of @key_file. - - - the same @key_file. - - - - - a #GKeyFile - - - - - - Removes a comment above @key from @group_name. -If @key is %NULL then @comment will be removed above @group_name. -If both @key and @group_name are %NULL, then @comment will -be removed above the first group in the file. - - - %TRUE if the comment was removed, %FALSE otherwise - - - - - a #GKeyFile - - - - a group name, or %NULL - - - - a key - - - - - - Removes the specified group, @group_name, -from the key file. - - - %TRUE if the group was removed, %FALSE otherwise - - - - - a #GKeyFile - - - - a group name - - - - - - Removes @key in @group_name from the key file. - - - %TRUE if the key was removed, %FALSE otherwise - - - - - a #GKeyFile - - - - a group name - - - - a key name to remove - - - - - - Writes the contents of @key_file to @filename using -g_file_set_contents(). - -This function can fail for any of the reasons that -g_file_set_contents() may fail. - - - %TRUE if successful, else %FALSE with @error set - - - - - a #GKeyFile - - - - the name of the file to write to - - - - - - Associates a new boolean value with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - %TRUE or %FALSE - - - - - - Associates a list of boolean values with @key under @group_name. -If @key cannot be found then it is created. -If @group_name is %NULL, the start_group is used. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an array of boolean values - - - - - - length of @list - - - - - - Places a comment above @key from @group_name. - -If @key is %NULL then @comment will be written above @group_name. -If both @key and @group_name are %NULL, then @comment will be -written above the first group in the file. - -Note that this function prepends a '#' comment marker to -each line of @comment. - - - %TRUE if the comment was written, %FALSE otherwise - - - - - a #GKeyFile - - - - a group name, or %NULL - - - - a key - - - - a comment - - - - - - Associates a new double value with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a double value - - - - - - Associates a list of double values with @key under -@group_name. If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an array of double values - - - - - - number of double values in @list - - - - - - Associates a new integer value with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an integer value - - - - - - Associates a new integer value with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an integer value - - - - - - Associates a list of integer values with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an array of integer values - - - - - - number of integer values in @list - - - - - - Sets the character which is used to separate -values in lists. Typically ';' or ',' are used -as separators. The default list separator is ';'. - - - - - - - a #GKeyFile - - - - the separator - - - - - - Associates a string value for @key and @locale under @group_name. -If the translation for @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier - - - - a string - - - - - - Associates a list of string values for @key and @locale under -@group_name. If the translation for @key cannot be found then -it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a locale identifier - - - - a %NULL-terminated array of locale string values - - - - - - the length of @list - - - - - - Associates a new string value with @key under @group_name. -If @key cannot be found then it is created. -If @group_name cannot be found then it is created. -Unlike g_key_file_set_value(), this function handles characters -that need escaping, such as newlines. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a string - - - - - - Associates a list of string values for @key under @group_name. -If @key cannot be found then it is created. -If @group_name cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an array of string values - - - - - - number of string values in @list - - - - - - Associates a new integer value with @key under @group_name. -If @key cannot be found then it is created. - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - an integer value - - - - - - Associates a new value with @key under @group_name. - -If @key cannot be found then it is created. If @group_name cannot -be found then it is created. To set an UTF-8 string which may contain -characters that need escaping (such as newlines or spaces), use -g_key_file_set_string(). - - - - - - - a #GKeyFile - - - - a group name - - - - a key - - - - a string - - - - - - This function outputs @key_file as a string. - -Note that this function never reports an error, -so it is safe to pass %NULL as @error. - - - a newly allocated string holding - the contents of the #GKeyFile - - - - - a #GKeyFile - - - - return location for the length of the - returned string, or %NULL - - - - - - Decreases the reference count of @key_file by 1. If the reference count -reaches zero, frees the key file and all its allocated memory. - - - - - - - a #GKeyFile - - - - - - - - - - - - Error codes returned by key file parsing. - - - the text being parsed was in - an unknown encoding - - - document was ill-formed - - - the file was not found - - - a requested key was not found - - - a requested group was not found - - - a value could not be parsed - - - - Flags which influence the parsing. - - - No flags, default behaviour - - - Use this flag if you plan to write the - (possibly modified) contents of the key file back to a file; - otherwise all comments will be lost when the key file is - written back. - - - Use this flag if you plan to write the - (possibly modified) contents of the key file back to a file; - otherwise only the translations for the current language will be - written back. - - - - Hints the compiler that the expression is likely to evaluate to -a true value. The compiler may use this information for optimizations. - -|[<!-- language="C" --> -if (G_LIKELY (random () != 1)) - g_print ("not one"); -]| - - - - the expression - - - - - Specifies one of the possible types of byte order. -See #G_BYTE_ORDER. - - - - - The natural logarithm of 10. - - - - - The natural logarithm of 2. - - - - - Works like g_mutex_lock(), but for a lock defined with -#G_LOCK_DEFINE. - - - - the name of the lock - - - - - The #G_LOCK_ macros provide a convenient interface to #GMutex. -#G_LOCK_DEFINE defines a lock. It can appear in any place where -variable definitions may appear in programs, i.e. in the first block -of a function or outside of functions. The @name parameter will be -mangled to get the name of the #GMutex. This means that you -can use names of existing variables as the parameter - e.g. the name -of the variable you intend to protect with the lock. Look at our -give_me_next_number() example using the #G_LOCK macros: - -Here is an example for using the #G_LOCK convenience macros: -|[<!-- language="C" --> - G_LOCK_DEFINE (current_number); - - int - give_me_next_number (void) - { - static int current_number = 0; - int ret_val; - - G_LOCK (current_number); - ret_val = current_number = calc_next_number (current_number); - G_UNLOCK (current_number); - - return ret_val; - } -]| - - - - the name of the lock - - - - - This works like #G_LOCK_DEFINE, but it creates a static object. - - - - the name of the lock - - - - - This declares a lock, that is defined with #G_LOCK_DEFINE in another -module. - - - - the name of the lock - - - - - - - - - - - - Multiplying the base 2 exponent by this number yields the base 10 exponent. - - - - - Defines the log domain. See [Log Domains](#log-domains). - -Libraries should define this so that any messages -which they log can be differentiated from messages from other -libraries and application code. But be careful not to define -it in any public header files. - -Log domains must be unique, and it is recommended that they are the -application or library name, optionally followed by a hyphen and a sub-domain -name. For example, `bloatpad` or `bloatpad-io`. - -If undefined, it defaults to the default %NULL (or `""`) log domain; this is -not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG` -environment variable. - -For example, GTK+ uses this in its `Makefile.am`: -|[ -AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" -]| - -Applications can choose to leave it as the default %NULL (or `""`) -domain. However, defining the domain offers the same advantages as -above. - - - - - GLib log levels that are considered fatal by default. - -This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - - - Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. -Higher bits can be used for user-defined log levels. - - - - - The #GList struct is used for each element in a doubly-linked list. - - - holds the element's data, which can be a pointer to any kind - of data, or any integer value using the - [Type Conversion Macros][glib-Type-Conversion-Macros] - - - - contains the link to the next element in the list - - - - - - contains the link to the previous element in the list - - - - - - Allocates space for one #GList element. It is called by -g_list_append(), g_list_prepend(), g_list_insert() and -g_list_insert_sorted() and so is rarely used on its own. - - - a pointer to the newly-allocated #GList element - - - - - - - Adds a new element on to the end of the list. - -Note that the return value is the new start of the list, -if @list was empty; make sure you store the new value. - -g_list_append() has to traverse the entire list to find the end, -which is inefficient when adding multiple elements. A common idiom -to avoid the inefficiency is to use g_list_prepend() and reverse -the list with g_list_reverse() when all elements have been added. - -|[<!-- language="C" --> -// Notice that these are initialized to the empty list. -GList *string_list = NULL, *number_list = NULL; - -// This is a list of strings. -string_list = g_list_append (string_list, "first"); -string_list = g_list_append (string_list, "second"); - -// This is a list of integers. -number_list = g_list_append (number_list, GINT_TO_POINTER (27)); -number_list = g_list_append (number_list, GINT_TO_POINTER (14)); -]| - - - either @list or the new start of the #GList if @list was %NULL - - - - - - - a pointer to a #GList - - - - - - the data for the new element - - - - - - Adds the second #GList onto the end of the first #GList. -Note that the elements of the second #GList are not copied. -They are used directly. - -This function is for example used to move an element in the list. -The following example moves an element to the top of the list: -|[<!-- language="C" --> -list = g_list_remove_link (list, llink); -list = g_list_concat (llink, list); -]| - - - the start of the new #GList, which equals @list1 if not %NULL - - - - - - - a #GList, this must point to the top of the list - - - - - - the #GList to add to the end of the first #GList, - this must point to the top of the list - - - - - - - - Copies a #GList. - -Note that this is a "shallow" copy. If the list elements -consist of pointers to data, the pointers are copied but -the actual data is not. See g_list_copy_deep() if you need -to copy the data as well. - - - the start of the new list that holds the same data as @list - - - - - - - a #GList, this must point to the top of the list - - - - - - - - Makes a full (deep) copy of a #GList. - -In contrast with g_list_copy(), this function uses @func to make -a copy of each list element, in addition to copying the list -container itself. - -@func, as a #GCopyFunc, takes two arguments, the data to be copied -and a @user_data pointer. On common processor architectures, it's safe to -pass %NULL as @user_data if the copy function takes only one argument. You -may get compiler warnings from this though if compiling with GCC’s -`-Wcast-function-type` warning. - -For instance, if @list holds a list of GObjects, you can do: -|[<!-- language="C" --> -another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); -]| - -And, to entirely free the new list, you could do: -|[<!-- language="C" --> -g_list_free_full (another_list, g_object_unref); -]| - - - the start of the new list that holds a full copy of @list, - use g_list_free_full() to free it - - - - - - - a #GList, this must point to the top of the list - - - - - - a copy function used to copy every element in the list - - - - user data passed to the copy function @func, or %NULL - - - - - - Removes the node link_ from the list and frees it. -Compare this to g_list_remove_link() which removes the node -without freeing it. - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - node to delete from @list - - - - - - - - Finds the element in a #GList which contains the given data. - - - the found #GList element, or %NULL if it is not found - - - - - - - a #GList, this must point to the top of the list - - - - - - the element data to find - - - - - - Finds an element in a #GList, using a supplied function to -find the desired element. It iterates over the list, calling -the given function which should return 0 when the desired -element is found. The function takes two #gconstpointer arguments, -the #GList element's data as the first argument and the -given user data. - - - the found #GList element, or %NULL if it is not found - - - - - - - a #GList, this must point to the top of the list - - - - - - user data passed to the function - - - - the function to call for each element. - It should return 0 when the desired element is found - - - - - - Gets the first element in a #GList. - - - the first element in the #GList, - or %NULL if the #GList has no elements - - - - - - - any #GList element - - - - - - - - Calls a function for each element of a #GList. - -It is safe for @func to remove the element from @list, but it must -not modify any part of the list after that element. - - - - - - - a #GList, this must point to the top of the list - - - - - - the function to call with each element's data - - - - user data to pass to the function - - - - - - Frees all of the memory used by a #GList. -The freed elements are returned to the slice allocator. - -If list elements contain dynamically-allocated memory, you should -either use g_list_free_full() or free them manually first. - -It can be combined with g_steal_pointer() to ensure the list head pointer -is not left dangling: -|[<!-- language="C" --> -GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ -g_list_free (g_steal_pointer (&list_of_borrowed_things)); -]| - - - - - - - a #GList - - - - - - - - Frees one #GList element, but does not update links from the next and -previous elements in the list, so you should not call this function on an -element that is currently part of a list. - -It is usually used after g_list_remove_link(). - - - - - - - a #GList element - - - - - - - - Convenience method, which frees all the memory used by a #GList, -and calls @free_func on every element's data. - -@free_func must not modify the list (eg, by removing the freed -element from it). - -It can be combined with g_steal_pointer() to ensure the list head pointer -is not left dangling ­— this also has the nice property that the head pointer -is cleared before any of the list elements are freed, to prevent double frees -from @free_func: -|[<!-- language="C" --> -GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ -g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); -]| - - - - - - - a pointer to a #GList - - - - - - the function to be called to free each element's data - - - - - - Gets the position of the element containing -the given data (starting from 0). - - - the index of the element containing the data, - or -1 if the data is not found - - - - - a #GList, this must point to the top of the list - - - - - - the data to find - - - - - - Inserts a new element into the list at the given position. - - - the (possibly changed) start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the list - - - - - - the data for the new element - - - - the position to insert the element. If this is - negative, or is larger than the number of elements in the - list, the new element is added on to the end of the list. - - - - - - Inserts a new element into the list before the given position. - - - the (possibly changed) start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the list - - - - - - the list element before which the new element - is inserted or %NULL to insert at the end of the list - - - - - - the data for the new element - - - - - - Inserts @link_ into the list before the given position. - - - the (possibly changed) start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the list - - - - - - the list element before which the new element - is inserted or %NULL to insert at the end of the list - - - - - - the list element to be added, which must not be part of - any other list - - - - - - - - Inserts a new element into the list, using the given comparison -function to determine its position. - -If you are adding many new elements to a list, and the number of -new elements is much larger than the length of the list, use -g_list_prepend() to add the new items and sort the list afterwards -with g_list_sort(). - - - the (possibly changed) start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the - already sorted list - - - - - - the data for the new element - - - - the function to compare elements in the list. It should - return a number > 0 if the first parameter comes after the - second parameter in the sort order. - - - - - - Inserts a new element into the list, using the given comparison -function to determine its position. - -If you are adding many new elements to a list, and the number of -new elements is much larger than the length of the list, use -g_list_prepend() to add the new items and sort the list afterwards -with g_list_sort(). - - - the (possibly changed) start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the - already sorted list - - - - - - the data for the new element - - - - the function to compare elements in the list. It should - return a number > 0 if the first parameter comes after the - second parameter in the sort order. - - - - user data to pass to comparison function - - - - - - Gets the last element in a #GList. - - - the last element in the #GList, - or %NULL if the #GList has no elements - - - - - - - any #GList element - - - - - - - - Gets the number of elements in a #GList. - -This function iterates over the whole list to count its elements. -Use a #GQueue instead of a GList if you regularly need the number -of items. To check whether the list is non-empty, it is faster to check -@list against %NULL. - - - the number of elements in the #GList - - - - - a #GList, this must point to the top of the list - - - - - - - - Gets the element at the given position in a #GList. - -This iterates over the list until it reaches the @n-th position. If you -intend to iterate over every element, it is better to use a for-loop as -described in the #GList introduction. - - - the element, or %NULL if the position is off - the end of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - the position of the element, counting from 0 - - - - - - Gets the data of the element at the given position. - -This iterates over the list until it reaches the @n-th position. If you -intend to iterate over every element, it is better to use a for-loop as -described in the #GList introduction. - - - the element's data, or %NULL if the position - is off the end of the #GList - - - - - a #GList, this must point to the top of the list - - - - - - the position of the element - - - - - - Gets the element @n places before @list. - - - the element, or %NULL if the position is - off the end of the #GList - - - - - - - a #GList - - - - - - the position of the element, counting from 0 - - - - - - Gets the position of the given element -in the #GList (starting from 0). - - - the position of the element in the #GList, - or -1 if the element is not found - - - - - a #GList, this must point to the top of the list - - - - - - an element in the #GList - - - - - - - - Prepends a new element on to the start of the list. - -Note that the return value is the new start of the list, -which will have changed, so make sure you store the new value. - -|[<!-- language="C" --> -// Notice that it is initialized to the empty list. -GList *list = NULL; - -list = g_list_prepend (list, "last"); -list = g_list_prepend (list, "first"); -]| - -Do not use this function to prepend a new element to a different -element than the start of the list. Use g_list_insert_before() instead. - - - a pointer to the newly prepended element, which is the new - start of the #GList - - - - - - - a pointer to a #GList, this must point to the top of the list - - - - - - the data for the new element - - - - - - Removes an element from a #GList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GList is unchanged. - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - the data of the element to remove - - - - - - Removes all list nodes with data equal to @data. -Returns the new head of the list. Contrast with -g_list_remove() which removes only the first node -matching the given data. - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - data to remove - - - - - - Removes an element from a #GList, without freeing the element. -The removed element's prev and next links are set to %NULL, so -that it becomes a self-contained list with one element. - -This function is for example used to move an element in the list -(see the example for g_list_concat()) or to remove an element in -the list before freeing its data: -|[<!-- language="C" --> -list = g_list_remove_link (list, llink); -free_some_data_that_may_access_the_list_again (llink->data); -g_list_free (llink); -]| - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - an element in the #GList - - - - - - - - Reverses a #GList. -It simply switches the next and prev pointers of each element. - - - the start of the reversed #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - - - Sorts a #GList using the given comparison function. The algorithm -used is a stable sort. - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - the comparison function used to sort the #GList. - This function is passed the data from 2 elements of the #GList - and should return 0 if they are equal, a negative value if the - first element comes before the second, or a positive value if - the first element comes after the second. - - - - - - Like g_list_sort(), but the comparison function accepts -a user data argument. - - - the (possibly changed) start of the #GList - - - - - - - a #GList, this must point to the top of the list - - - - - - comparison function - - - - user data to pass to comparison function - - - - - - - Structure representing a single field in a structured log entry. See -g_log_structured() for details. - -Log fields may contain arbitrary values, including binary with embedded nul -bytes. If the field contains a string, the string must be UTF-8 encoded and -have a trailing nul byte. Otherwise, @length must be set to a non-negative -value. - - - field name (UTF-8 string) - - - - field value (arbitrary bytes) - - - - length of @value, in bytes, or -1 if it is nul-terminated - - - - - Specifies the prototype of log handler functions. - -The default log handler, g_log_default_handler(), automatically appends a -new-line character to @message when printing it. It is advised that any -custom log handler functions behave similarly, so that logging calls in user -code do not need modifying to add a new-line character to the message if the -log handler is changed. - -This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - - - - - the log domain of the message - - - - the log level of the message (including the - fatal and recursion flags) - - - - the message to process - - - - user data, set in g_log_set_handler() - - - - - - Flags specifying the level of log messages. - -It is possible to change how GLib treats messages of the various -levels using g_log_set_handler() and g_log_set_fatal_mask(). - - - internal flag - - - internal flag - - - log level for errors, see g_error(). - This level is also used for messages produced by g_assert(). - - - log level for critical warning messages, see - g_critical(). - This level is also used for messages produced by g_return_if_fail() - and g_return_val_if_fail(). - - - log level for warnings, see g_warning() - - - log level for messages, see g_message() - - - log level for informational messages, see g_info() - - - log level for debug messages, see g_debug() - - - a mask including all log levels - - - - Writer function for log entries. A log entry is a collection of one or more -#GLogFields, using the standard [field names from journal -specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html). -See g_log_structured() for more information. - -Writer functions must ignore fields which they do not recognise, unless they -can write arbitrary binary output, as field values may be arbitrary binary. - -@log_level is guaranteed to be included in @fields as the `PRIORITY` field, -but is provided separately for convenience of deciding whether or where to -output the log entry. - -Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log -message successfully or if they deliberately ignored it. If there was an -error handling the message (for example, if the writer function is meant to -send messages to a remote logging server and there is a network error), it -should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be -chained and fall back to simpler handlers in case of failure. - - - %G_LOG_WRITER_HANDLED if the log entry was handled successfully; - %G_LOG_WRITER_UNHANDLED otherwise - - - - - log level of the message - - - - fields forming the message - - - - - - number of @fields - - - - user data passed to g_log_set_writer_func() - - - - - - Return values from #GLogWriterFuncs to indicate whether the given log entry -was successfully handled by the writer, or whether there was an error in -handling it (and hence a fallback writer should be used). - -If a #GLogWriterFunc ignores a log entry, it should return -%G_LOG_WRITER_HANDLED. - - - Log writer has handled the log entry. - - - Log writer could not handle the log entry. - - - - The major version number of the GLib library. - -Like #glib_major_version, but from the headers used at -application compile time, rather than from the library -linked against at application run time. - - - - - The maximum value which can be held in a #gint16. - - - - - The maximum value which can be held in a #gint32. - - - - - The maximum value which can be held in a #gint64. - - - - - The maximum value which can be held in a #gint8. - - - - - The maximum value which can be held in a #guint16. - - - - - The maximum value which can be held in a #guint32. - - - - - The maximum value which can be held in a #guint64. - - - - - The maximum value which can be held in a #guint8. - - - - - The micro version number of the GLib library. - -Like #gtk_micro_version, but from the headers used at -application compile time, rather than from the library -linked against at application run time. - - - - - The minimum value which can be held in a #gint16. - - - - - The minimum value which can be held in a #gint32. - - - - - The minimum value which can be held in a #gint64. - - - - - The minimum value which can be held in a #gint8. - - - - - The minor version number of the GLib library. - -Like #gtk_minor_version, but from the headers used at -application compile time, rather than from the library -linked against at application run time. - - - - - - - - - The `GMainContext` struct is an opaque data -type representing a set of sources to be handled in a main loop. - - - Creates a new #GMainContext structure. - - - the new #GMainContext - - - - - Tries to become the owner of the specified context. -If some other thread is the owner of the context, -returns %FALSE immediately. Ownership is properly -recursive: the owner can require ownership again -and will release ownership when g_main_context_release() -is called as many times as g_main_context_acquire(). - -You must be the owner of a context before you -can call g_main_context_prepare(), g_main_context_query(), -g_main_context_check(), g_main_context_dispatch(). - - - %TRUE if the operation succeeded, and - this thread is now the owner of @context. - - - - - a #GMainContext - - - - - - Adds a file descriptor to the set of file descriptors polled for -this context. This will very seldom be used directly. Instead -a typical event source will use g_source_add_unix_fd() instead. - - - - - - - a #GMainContext (or %NULL for the default context) - - - - a #GPollFD structure holding information about a file - descriptor to watch. - - - - the priority for this file descriptor which should be - the same as the priority used for g_source_attach() to ensure that the - file descriptor is polled whenever the results may be needed. - - - - - - Passes the results of polling back to the main loop. - -You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - - - %TRUE if some sources are ready to be dispatched. - - - - - a #GMainContext - - - - the maximum numerical priority of sources to check - - - - array of #GPollFD's that was passed to - the last call to g_main_context_query() - - - - - - return value of g_main_context_query() - - - - - - Dispatches all pending sources. - -You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - - - - - - - a #GMainContext - - - - - - Finds a source with the given source functions and user data. If -multiple sources exist with the same source function and user data, -the first one found will be returned. - - - the source, if one was found, otherwise %NULL - - - - - a #GMainContext (if %NULL, the default context will be used). - - - - the @source_funcs passed to g_source_new(). - - - - the user data from the callback. - - - - - - Finds a #GSource given a pair of context and ID. - -It is a programmer error to attempt to look up a non-existent source. - -More specifically: source IDs can be reissued after a source has been -destroyed and therefore it is never valid to use this function with a -source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the -idle may already have run and been removed by the time this function -is called on its (now invalid) source ID. This source ID may have -been reissued, leading to the operation being performed against the -wrong source. - - - the #GSource - - - - - a #GMainContext (if %NULL, the default context will be used) - - - - the source ID, as returned by g_source_get_id(). - - - - - - Finds a source with the given user data for the callback. If -multiple sources exist with the same user data, the first -one found will be returned. - - - the source, if one was found, otherwise %NULL - - - - - a #GMainContext - - - - the user_data for the callback. - - - - - - Gets the poll function set by g_main_context_set_poll_func(). - - - the poll function - - - - - a #GMainContext - - - - - - Invokes a function in such a way that @context is owned during the -invocation of @function. - -If @context is %NULL then the global default main context — as -returned by g_main_context_default() — is used. - -If @context is owned by the current thread, @function is called -directly. Otherwise, if @context is the thread-default main context -of the current thread and g_main_context_acquire() succeeds, then -@function is called and g_main_context_release() is called -afterwards. - -In any other case, an idle source is created to call @function and -that source is attached to @context (presumably to be run in another -thread). The idle source is attached with #G_PRIORITY_DEFAULT -priority. If you want a different priority, use -g_main_context_invoke_full(). - -Note that, as with normal idle functions, @function should probably -return %FALSE. If it returns %TRUE, it will be continuously run in a -loop (and may prevent this call from returning). - - - - - - - a #GMainContext, or %NULL - - - - function to call - - - - data to pass to @function - - - - - - Invokes a function in such a way that @context is owned during the -invocation of @function. - -This function is the same as g_main_context_invoke() except that it -lets you specify the priority in case @function ends up being -scheduled as an idle and also lets you give a #GDestroyNotify for @data. - -@notify should not assume that it is called from any particular -thread or with any particular context acquired. - - - - - - - a #GMainContext, or %NULL - - - - the priority at which to run @function - - - - function to call - - - - data to pass to @function - - - - a function to call when @data is no longer in use, or %NULL. - - - - - - Determines whether this thread holds the (recursive) -ownership of this #GMainContext. This is useful to -know before waiting on another thread that may be -blocking to get ownership of @context. - - - %TRUE if current thread is owner of @context. - - - - - a #GMainContext - - - - - - Runs a single iteration for the given main loop. This involves -checking to see if any event sources are ready to be processed, -then if no events sources are ready and @may_block is %TRUE, waiting -for a source to become ready, then dispatching the highest priority -events sources that are ready. Otherwise, if @may_block is %FALSE -sources are not waited to become ready, only those highest priority -events sources will be dispatched (if any), that are ready at this -given moment without further waiting. - -Note that even when @may_block is %TRUE, it is still possible for -g_main_context_iteration() to return %FALSE, since the wait may -be interrupted for other reasons than an event source becoming ready. - - - %TRUE if events were dispatched. - - - - - a #GMainContext (if %NULL, the default context will be used) - - - - whether the call may block. - - - - - - Checks if any sources have pending events for the given context. - - - %TRUE if events are pending. - - - - - a #GMainContext (if %NULL, the default context will be used) - - - - - - Pops @context off the thread-default context stack (verifying that -it was on the top of the stack). - - - - - - - a #GMainContext object, or %NULL - - - - - - Prepares to poll sources within a main loop. The resulting information -for polling is determined by calling g_main_context_query (). - -You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - - - %TRUE if some source is ready to be dispatched - prior to polling. - - - - - a #GMainContext - - - - location to store priority of highest priority - source already ready. - - - - - - Acquires @context and sets it as the thread-default context for the -current thread. This will cause certain asynchronous operations -(such as most [gio][gio]-based I/O) which are -started in this thread to run under @context and deliver their -results to its main loop, rather than running under the global -default context in the main thread. Note that calling this function -changes the context returned by g_main_context_get_thread_default(), -not the one returned by g_main_context_default(), so it does not affect -the context used by functions like g_idle_add(). - -Normally you would call this function shortly after creating a new -thread, passing it a #GMainContext which will be run by a -#GMainLoop in that thread, to set a new default context for all -async operations in that thread. In this case you may not need to -ever call g_main_context_pop_thread_default(), assuming you want the -new #GMainContext to be the default for the whole lifecycle of the -thread. - -If you don't have control over how the new thread was created (e.g. -in the new thread isn't newly created, or if the thread life -cycle is managed by a #GThreadPool), it is always suggested to wrap -the logic that needs to use the new #GMainContext inside a -g_main_context_push_thread_default() / g_main_context_pop_thread_default() -pair, otherwise threads that are re-used will end up never explicitly -releasing the #GMainContext reference they hold. - -In some cases you may want to schedule a single operation in a -non-default context, or temporarily use a non-default context in -the main thread. In that case, you can wrap the call to the -asynchronous operation inside a -g_main_context_push_thread_default() / -g_main_context_pop_thread_default() pair, but it is up to you to -ensure that no other asynchronous operations accidentally get -started while the non-default context is active. - -Beware that libraries that predate this function may not correctly -handle being used from a thread with a thread-default context. Eg, -see g_file_supports_thread_contexts(). - - - - - - - a #GMainContext, or %NULL for the global default context - - - - - - Determines information necessary to poll this main loop. - -You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. - - - the number of records actually stored in @fds, - or, if more than @n_fds records need to be stored, the number - of records that need to be stored. - - - - - a #GMainContext - - - - maximum priority source to check - - - - location to store timeout to be used in polling - - - - location to - store #GPollFD records that need to be polled. - - - - - - length of @fds. - - - - - - Increases the reference count on a #GMainContext object by one. - - - the @context that was passed in (since 2.6) - - - - - a #GMainContext - - - - - - Releases ownership of a context previously acquired by this thread -with g_main_context_acquire(). If the context was acquired multiple -times, the ownership will be released only when g_main_context_release() -is called as many times as it was acquired. - - - - - - - a #GMainContext - - - - - - Removes file descriptor from the set of file descriptors to be -polled for a particular context. - - - - - - - a #GMainContext - - - - a #GPollFD descriptor previously added with g_main_context_add_poll() - - - - - - Sets the function to use to handle polling of file descriptors. It -will be used instead of the poll() system call -(or GLib's replacement function, which is used where -poll() isn't available). - -This function could possibly be used to integrate the GLib event -loop with an external event loop. - - - - - - - a #GMainContext - - - - the function to call to poll all file descriptors - - - - - - Decreases the reference count on a #GMainContext object by one. If -the result is zero, free the context and free all associated memory. - - - - - - - a #GMainContext - - - - - - Tries to become the owner of the specified context, -as with g_main_context_acquire(). But if another thread -is the owner, atomically drop @mutex and wait on @cond until -that owner releases ownership or until @cond is signaled, then -try again (once) to become the owner. - Use g_main_context_is_owner() and separate locking instead. - - - %TRUE if the operation succeeded, and - this thread is now the owner of @context. - - - - - a #GMainContext - - - - a condition variable - - - - a mutex, currently held - - - - - - If @context is currently blocking in g_main_context_iteration() -waiting for a source to become ready, cause it to stop blocking -and return. Otherwise, cause the next invocation of -g_main_context_iteration() to return without blocking. - -This API is useful for low-level control over #GMainContext; for -example, integrating it with main loop implementations such as -#GMainLoop. - -Another related use for this function is when implementing a main -loop with a termination condition, computed from multiple threads: - -|[<!-- language="C" --> - #define NUM_TASKS 10 - static volatile gint tasks_remaining = NUM_TASKS; - ... - - while (g_atomic_int_get (&tasks_remaining) != 0) - g_main_context_iteration (NULL, TRUE); -]| - -Then in a thread: -|[<!-- language="C" --> - perform_work(); - - if (g_atomic_int_dec_and_test (&tasks_remaining)) - g_main_context_wakeup (NULL); -]| - - - - - - - a #GMainContext - - - - - - Returns the global default main context. This is the main context -used for main loop functions when a main loop is not explicitly -specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). - - - the global default main context. - - - - - Gets the thread-default #GMainContext for this thread. Asynchronous -operations that want to be able to be run in contexts other than -the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) - -If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. - - - the thread-default #GMainContext, or -%NULL if the thread-default context is the global default context. - - - - - Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. - - - the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. - - - - - - The `GMainLoop` struct is an opaque data type -representing the main event loop of a GLib or GTK+ application. - - - Creates a new #GMainLoop structure. - - - a new #GMainLoop. - - - - - a #GMainContext (if %NULL, the default context will be used). - - - - set to %TRUE to indicate that the loop is running. This -is not very important since calling g_main_loop_run() will set this to -%TRUE anyway. - - - - - - Returns the #GMainContext of @loop. - - - the #GMainContext of @loop - - - - - a #GMainLoop. - - - - - - Checks to see if the main loop is currently being run via g_main_loop_run(). - - - %TRUE if the mainloop is currently being run. - - - - - a #GMainLoop. - - - - - - Stops a #GMainLoop from running. Any calls to g_main_loop_run() -for the loop will return. - -Note that sources that have already been dispatched when -g_main_loop_quit() is called will still be executed. - - - - - - - a #GMainLoop - - - - - - Increases the reference count on a #GMainLoop object by one. - - - @loop - - - - - a #GMainLoop - - - - - - Runs a main loop until g_main_loop_quit() is called on the loop. -If this is called for the thread of the loop's #GMainContext, -it will process events from the loop, otherwise it will -simply wait. - - - - - - - a #GMainLoop - - - - - - Decreases the reference count on a #GMainLoop object by one. If -the result is zero, free the loop and free all associated memory. - - - - - - - a #GMainLoop - - - - - - - The #GMappedFile represents a file mapping created with -g_mapped_file_new(). It has only private members and should -not be accessed directly. - - - Maps a file into memory. On UNIX, this is using the mmap() function. - -If @writable is %TRUE, the mapped buffer may be modified, otherwise -it is an error to modify the mapped buffer. Modifications to the buffer -are not visible to other processes mapping the same file, and are not -written back to the file. - -Note that modifications of the underlying file might affect the contents -of the #GMappedFile. Therefore, mapping should only be used if the file -will not be modified, or if all modifications of the file are done -atomically (e.g. using g_file_set_contents()). - -If @filename is the name of an empty, regular file, the function -will successfully return an empty #GMappedFile. In other cases of -size 0 (e.g. device files such as /dev/null), @error will be set -to the #GFileError value #G_FILE_ERROR_INVAL. - - - a newly allocated #GMappedFile which must be unref'd - with g_mapped_file_unref(), or %NULL if the mapping failed. - - - - - The path of the file to load, in the GLib - filename encoding - - - - whether the mapping should be writable - - - - - - Maps a file into memory. On UNIX, this is using the mmap() function. - -If @writable is %TRUE, the mapped buffer may be modified, otherwise -it is an error to modify the mapped buffer. Modifications to the buffer -are not visible to other processes mapping the same file, and are not -written back to the file. - -Note that modifications of the underlying file might affect the contents -of the #GMappedFile. Therefore, mapping should only be used if the file -will not be modified, or if all modifications of the file are done -atomically (e.g. using g_file_set_contents()). - - - a newly allocated #GMappedFile which must be unref'd - with g_mapped_file_unref(), or %NULL if the mapping failed. - - - - - The file descriptor of the file to load - - - - whether the mapping should be writable - - - - - - This call existed before #GMappedFile had refcounting and is currently -exactly the same as g_mapped_file_unref(). - Use g_mapped_file_unref() instead. - - - - - - - a #GMappedFile - - - - - - Creates a new #GBytes which references the data mapped from @file. -The mapped contents of the file must not be modified after creating this -bytes object, because a #GBytes should be immutable. - - - A newly allocated #GBytes referencing data - from @file - - - - - a #GMappedFile - - - - - - Returns the contents of a #GMappedFile. - -Note that the contents may not be zero-terminated, -even if the #GMappedFile is backed by a text file. - -If the file is empty then %NULL is returned. - - - the contents of @file, or %NULL. - - - - - a #GMappedFile - - - - - - Returns the length of the contents of a #GMappedFile. - - - the length of the contents of @file. - - - - - a #GMappedFile - - - - - - Increments the reference count of @file by one. It is safe to call -this function from any thread. - - - the passed in #GMappedFile. - - - - - a #GMappedFile - - - - - - Decrements the reference count of @file by one. If the reference count -drops to 0, unmaps the buffer of @file and frees it. - -It is safe to call this function from any thread. - -Since 2.22 - - - - - - - a #GMappedFile - - - - - - - A mixed enumerated type and flags field. You must specify one type -(string, strdup, boolean, tristate). Additionally, you may optionally -bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. - -It is likely that this enum will be extended in the future to -support other types. - - - used to terminate the list of attributes - to collect - - - collect the string pointer directly from - the attribute_values[] array. Expects a parameter of type (const - char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the - attribute isn't present then the pointer will be set to %NULL - - - as with %G_MARKUP_COLLECT_STRING, but - expects a parameter of type (char **) and g_strdup()s the - returned pointer. The pointer must be freed with g_free() - - - expects a parameter of type (gboolean *) - and parses the attribute value as a boolean. Sets %FALSE if the - attribute isn't present. Valid boolean values consist of - (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", - "yes", "y", "1" - - - as with %G_MARKUP_COLLECT_BOOLEAN, but - in the case of a missing attribute a value is set that compares - equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is - implied - - - can be bitwise ORed with the other fields. - If present, allows the attribute not to appear. A default value - is set depending on what value type is used - - - - Error codes returned by markup parsing. - - - text being parsed was not valid UTF-8 - - - document contained nothing, or only whitespace - - - document was ill-formed - - - error should be set by #GMarkupParser - functions; element wasn't known - - - error should be set by #GMarkupParser - functions; attribute wasn't known - - - error should be set by #GMarkupParser - functions; content was invalid - - - error should be set by #GMarkupParser - functions; a required attribute was missing - - - - A parse context is used to parse a stream of bytes that -you expect to contain marked-up text. - -See g_markup_parse_context_new(), #GMarkupParser, and so -on for more details. - - - Creates a new parse context. A parse context is used to parse -marked-up documents. You can feed any number of documents into -a context, as long as no errors occur; once an error occurs, -the parse context can't continue to parse text (you have to -free it and create a new parse context). - - - a new #GMarkupParseContext - - - - - a #GMarkupParser - - - - one or more #GMarkupParseFlags - - - - user data to pass to #GMarkupParser functions - - - - user data destroy notifier called when - the parse context is freed - - - - - - Signals to the #GMarkupParseContext that all data has been -fed into the parse context with g_markup_parse_context_parse(). - -This function reports an error if the document isn't complete, -for example if elements are still open. - - - %TRUE on success, %FALSE if an error was set - - - - - a #GMarkupParseContext - - - - - - Frees a #GMarkupParseContext. - -This function can't be called from inside one of the -#GMarkupParser functions or while a subparser is pushed. - - - - - - - a #GMarkupParseContext - - - - - - Retrieves the name of the currently open element. - -If called from the start_element or end_element handlers this will -give the element_name as passed to those functions. For the parent -elements, see g_markup_parse_context_get_element_stack(). - - - the name of the currently open element, or %NULL - - - - - a #GMarkupParseContext - - - - - - Retrieves the element stack from the internal state of the parser. - -The returned #GSList is a list of strings where the first item is -the currently open tag (as would be returned by -g_markup_parse_context_get_element()) and the next item is its -immediate parent. - -This function is intended to be used in the start_element and -end_element handlers where g_markup_parse_context_get_element() -would merely return the name of the element that is being -processed. - - - the element stack, which must not be modified - - - - - - - a #GMarkupParseContext - - - - - - Retrieves the current line number and the number of the character on -that line. Intended for use in error messages; there are no strict -semantics for what constitutes the "current" line number other than -"the best number we could come up with for error messages." - - - - - - - a #GMarkupParseContext - - - - return location for a line number, or %NULL - - - - return location for a char-on-line number, or %NULL - - - - - - Returns the user_data associated with @context. - -This will either be the user_data that was provided to -g_markup_parse_context_new() or to the most recent call -of g_markup_parse_context_push(). - - - the provided user_data. The returned data belongs to - the markup context and will be freed when - g_markup_parse_context_free() is called. - - - - - a #GMarkupParseContext - - - - - - Feed some data to the #GMarkupParseContext. - -The data need not be valid UTF-8; an error will be signaled if -it's invalid. The data need not be an entire document; you can -feed a document into the parser incrementally, via multiple calls -to this function. Typically, as you receive data from a network -connection or file, you feed each received chunk of data into this -function, aborting the process if an error occurs. Once an error -is reported, no further data may be fed to the #GMarkupParseContext; -all errors are fatal. - - - %FALSE if an error occurred, %TRUE on success - - - - - a #GMarkupParseContext - - - - chunk of text to parse - - - - length of @text in bytes - - - - - - Completes the process of a temporary sub-parser redirection. - -This function exists to collect the user_data allocated by a -matching call to g_markup_parse_context_push(). It must be called -in the end_element handler corresponding to the start_element -handler during which g_markup_parse_context_push() was called. -You must not call this function from the error callback -- the -@user_data is provided directly to the callback in that case. - -This function is not intended to be directly called by users -interested in invoking subparsers. Instead, it is intended to -be used by the subparsers themselves to implement a higher-level -interface. - - - the user data passed to g_markup_parse_context_push() - - - - - a #GMarkupParseContext - - - - - - Temporarily redirects markup data to a sub-parser. - -This function may only be called from the start_element handler of -a #GMarkupParser. It must be matched with a corresponding call to -g_markup_parse_context_pop() in the matching end_element handler -(except in the case that the parser aborts due to an error). - -All tags, text and other data between the matching tags is -redirected to the subparser given by @parser. @user_data is used -as the user_data for that parser. @user_data is also passed to the -error callback in the event that an error occurs. This includes -errors that occur in subparsers of the subparser. - -The end tag matching the start tag for which this call was made is -handled by the previous parser (which is given its own user_data) -which is why g_markup_parse_context_pop() is provided to allow "one -last access" to the @user_data provided to this function. In the -case of error, the @user_data provided here is passed directly to -the error callback of the subparser and g_markup_parse_context_pop() -should not be called. In either case, if @user_data was allocated -then it ought to be freed from both of these locations. - -This function is not intended to be directly called by users -interested in invoking subparsers. Instead, it is intended to be -used by the subparsers themselves to implement a higher-level -interface. - -As an example, see the following implementation of a simple -parser that counts the number of tags encountered. - -|[<!-- language="C" --> -typedef struct -{ - gint tag_count; -} CounterData; - -static void -counter_start_element (GMarkupParseContext *context, - const gchar *element_name, - const gchar **attribute_names, - const gchar **attribute_values, - gpointer user_data, - GError **error) -{ - CounterData *data = user_data; - - data->tag_count++; -} - -static void -counter_error (GMarkupParseContext *context, - GError *error, - gpointer user_data) -{ - CounterData *data = user_data; - - g_slice_free (CounterData, data); -} - -static GMarkupParser counter_subparser = -{ - counter_start_element, - NULL, - NULL, - NULL, - counter_error -}; -]| - -In order to allow this parser to be easily used as a subparser, the -following interface is provided: - -|[<!-- language="C" --> -void -start_counting (GMarkupParseContext *context) -{ - CounterData *data = g_slice_new (CounterData); - - data->tag_count = 0; - g_markup_parse_context_push (context, &counter_subparser, data); -} - -gint -end_counting (GMarkupParseContext *context) -{ - CounterData *data = g_markup_parse_context_pop (context); - int result; - - result = data->tag_count; - g_slice_free (CounterData, data); - - return result; -} -]| - -The subparser would then be used as follows: - -|[<!-- language="C" --> -static void start_element (context, element_name, ...) -{ - if (strcmp (element_name, "count-these") == 0) - start_counting (context); - - // else, handle other tags... -} - -static void end_element (context, element_name, ...) -{ - if (strcmp (element_name, "count-these") == 0) - g_print ("Counted %d tags\n", end_counting (context)); - - // else, handle other tags... -} -]| - - - - - - - a #GMarkupParseContext - - - - a #GMarkupParser - - - - user data to pass to #GMarkupParser functions - - - - - - Increases the reference count of @context. - - - the same @context - - - - - a #GMarkupParseContext - - - - - - Decreases the reference count of @context. When its reference count -drops to 0, it is freed. - - - - - - - a #GMarkupParseContext - - - - - - - Flags that affect the behaviour of the parser. - - - flag you should not use - - - When this flag is set, CDATA marked - sections are not passed literally to the @passthrough function of - the parser. Instead, the content of the section (without the - `<![CDATA[` and `]]>`) is - passed to the @text function. This flag was added in GLib 2.12 - - - Normally errors caught by GMarkup - itself have line/column information prefixed to them to let the - caller know the location of the error. When this flag is set the - location information is also prefixed to errors generated by the - #GMarkupParser implementation functions - - - Ignore (don't report) qualified - attributes and tags, along with their contents. A qualified - attribute or tag is one that contains ':' in its name (ie: is in - another namespace). Since: 2.40. - - - - Any of the fields in #GMarkupParser can be %NULL, in which case they -will be ignored. Except for the @error function, any of these callbacks -can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, -%G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT -errors are intended to be set from these callbacks. If you set an error -from a callback, g_markup_parse_context_parse() will report that error -back to its caller. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A GMatchInfo is an opaque struct used to return information about -matches. - - - Returns a new string containing the text in @string_to_expand with -references and escape sequences expanded. References refer to the last -match done with @string against @regex and have the same syntax used by -g_regex_replace(). - -The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was -passed to g_regex_new(). - -The backreferences are extracted from the string passed to the match -function, so you cannot call this function after freeing the string. - -@match_info may be %NULL in which case @string_to_expand must not -contain references. For instance "foo\n" does not refer to an actual -pattern and '\n' merely will be replaced with \n character, -while to expand "\0" (whole match) one needs the result of a match. -Use g_regex_check_replacement() to find out whether @string_to_expand -contains references. - - - the expanded string, or %NULL if an error occurred - - - - - a #GMatchInfo or %NULL - - - - the string to expand - - - - - - Retrieves the text matching the @match_num'th capturing -parentheses. 0 is the full text of the match, 1 is the first paren -set, 2 the second, and so on. - -If @match_num is a valid sub pattern but it didn't match anything -(e.g. sub pattern 1, matching "b" against "(a)?b") then an empty -string is returned. - -If the match was obtained using the DFA algorithm, that is using -g_regex_match_all() or g_regex_match_all_full(), the retrieved -string is not that of a set of parentheses but that of a matched -substring. Substrings are matched in reverse order of length, so -0 is the longest match. - -The string is fetched from the string passed to the match function, -so you cannot call this function after freeing the string. - - - The matched substring, or %NULL if an error - occurred. You have to free the string yourself - - - - - #GMatchInfo structure - - - - number of the sub expression - - - - - - Bundles up pointers to each of the matching substrings from a match -and stores them in an array of gchar pointers. The first element in -the returned array is the match number 0, i.e. the entire matched -text. - -If a sub pattern didn't match anything (e.g. sub pattern 1, matching -"b" against "(a)?b") then an empty string is inserted. - -If the last match was obtained using the DFA algorithm, that is using -g_regex_match_all() or g_regex_match_all_full(), the retrieved -strings are not that matched by sets of parentheses but that of the -matched substring. Substrings are matched in reverse order of length, -so the first one is the longest match. - -The strings are fetched from the string passed to the match function, -so you cannot call this function after freeing the string. - - - a %NULL-terminated array of gchar * - pointers. It must be freed using g_strfreev(). If the previous - match failed %NULL is returned - - - - - - - a #GMatchInfo structure - - - - - - Retrieves the text matching the capturing parentheses named @name. - -If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") -then an empty string is returned. - -The string is fetched from the string passed to the match function, -so you cannot call this function after freeing the string. - - - The matched substring, or %NULL if an error - occurred. You have to free the string yourself - - - - - #GMatchInfo structure - - - - name of the subexpression - - - - - - Retrieves the position in bytes of the capturing parentheses named @name. - -If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") -then @start_pos and @end_pos are set to -1 and %TRUE is returned. - - - %TRUE if the position was fetched, %FALSE otherwise. - If the position cannot be fetched, @start_pos and @end_pos - are left unchanged. - - - - - #GMatchInfo structure - - - - name of the subexpression - - - - pointer to location where to store - the start position, or %NULL - - - - pointer to location where to store - the end position, or %NULL - - - - - - Retrieves the position in bytes of the @match_num'th capturing -parentheses. 0 is the full text of the match, 1 is the first -paren set, 2 the second, and so on. - -If @match_num is a valid sub pattern but it didn't match anything -(e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos -and @end_pos are set to -1 and %TRUE is returned. - -If the match was obtained using the DFA algorithm, that is using -g_regex_match_all() or g_regex_match_all_full(), the retrieved -position is not that of a set of parentheses but that of a matched -substring. Substrings are matched in reverse order of length, so -0 is the longest match. - - - %TRUE if the position was fetched, %FALSE otherwise. If - the position cannot be fetched, @start_pos and @end_pos are left - unchanged - - - - - #GMatchInfo structure - - - - number of the sub expression - - - - pointer to location where to store - the start position, or %NULL - - - - pointer to location where to store - the end position, or %NULL - - - - - - If @match_info is not %NULL, calls g_match_info_unref(); otherwise does -nothing. - - - - - - - a #GMatchInfo, or %NULL - - - - - - Retrieves the number of matched substrings (including substring 0, -that is the whole matched text), so 1 is returned if the pattern -has no substrings in it and 0 is returned if the match failed. - -If the last match was obtained using the DFA algorithm, that is -using g_regex_match_all() or g_regex_match_all_full(), the retrieved -count is not that of the number of capturing parentheses but that of -the number of matched substrings. - - - Number of matched substrings, or -1 if an error occurred - - - - - a #GMatchInfo structure - - - - - - Returns #GRegex object used in @match_info. It belongs to Glib -and must not be freed. Use g_regex_ref() if you need to keep it -after you free @match_info object. - - - #GRegex object used in @match_info - - - - - a #GMatchInfo - - - - - - Returns the string searched with @match_info. This is the -string passed to g_regex_match() or g_regex_replace() so -you may not free it before calling this function. - - - the string searched with @match_info - - - - - a #GMatchInfo - - - - - - Usually if the string passed to g_regex_match*() matches as far as -it goes, but is too short to match the entire pattern, %FALSE is -returned. There are circumstances where it might be helpful to -distinguish this case from other cases in which there is no match. - -Consider, for example, an application where a human is required to -type in data for a field with specific formatting requirements. An -example might be a date in the form ddmmmyy, defined by the pattern -"^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". -If the application sees the user’s keystrokes one by one, and can -check that what has been typed so far is potentially valid, it is -able to raise an error as soon as a mistake is made. - -GRegex supports the concept of partial matching by means of the -#G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags. -When they are used, the return code for -g_regex_match() or g_regex_match_full() is, as usual, %TRUE -for a complete match, %FALSE otherwise. But, when these functions -return %FALSE, you can check if the match was partial calling -g_match_info_is_partial_match(). - -The difference between #G_REGEX_MATCH_PARTIAL_SOFT and -#G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered -with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a -possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching -stops at the partial match. -When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD -are set, the latter takes precedence. - -There were formerly some restrictions on the pattern for partial matching. -The restrictions no longer apply. - -See pcrepartial(3) for more information on partial matching. - - - %TRUE if the match was partial, %FALSE otherwise - - - - - a #GMatchInfo structure - - - - - - Returns whether the previous match operation succeeded. - - - %TRUE if the previous match operation succeeded, - %FALSE otherwise - - - - - a #GMatchInfo structure - - - - - - Scans for the next match using the same parameters of the previous -call to g_regex_match_full() or g_regex_match() that returned -@match_info. - -The match is done on the string passed to the match function, so you -cannot free it before calling this function. - - - %TRUE is the string matched, %FALSE otherwise - - - - - a #GMatchInfo structure - - - - - - Increases reference count of @match_info by 1. - - - @match_info - - - - - a #GMatchInfo - - - - - - Decreases reference count of @match_info by 1. When reference count drops -to zero, it frees all the memory associated with the match_info structure. - - - - - - - a #GMatchInfo - - - - - - - A set of functions used to perform memory allocation. The same #GMemVTable must -be used for all allocations in the same program; a call to g_mem_set_vtable(), -if it exists, should be prior to any use of GLib. - -This functions related to this has been deprecated in 2.46, and no longer work. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GMutex struct is an opaque data structure to represent a mutex -(mutual exclusion). It can be used to protect data against shared -access. - -Take for example the following function: -|[<!-- language="C" --> - int - give_me_next_number (void) - { - static int current_number = 0; - - // now do a very complicated calculation to calculate the new - // number, this might for example be a random number generator - current_number = calc_next_number (current_number); - - return current_number; - } -]| -It is easy to see that this won't work in a multi-threaded -application. There current_number must be protected against shared -access. A #GMutex can be used as a solution to this problem: -|[<!-- language="C" --> - int - give_me_next_number (void) - { - static GMutex mutex; - static int current_number = 0; - int ret_val; - - g_mutex_lock (&mutex); - ret_val = current_number = calc_next_number (current_number); - g_mutex_unlock (&mutex); - - return ret_val; - } -]| -Notice that the #GMutex is not initialised to any particular value. -Its placement in static storage ensures that it will be initialised -to all-zeros, which is appropriate. - -If a #GMutex is placed in other contexts (eg: embedded in a struct) -then it must be explicitly initialised using g_mutex_init(). - -A #GMutex should only be accessed via g_mutex_ functions. - - - - - - - - - - - Frees the resources allocated to a mutex with g_mutex_init(). - -This function should not be used with a #GMutex that has been -statically allocated. - -Calling g_mutex_clear() on a locked mutex leads to undefined -behaviour. - -Sine: 2.32 - - - - - - - an initialized #GMutex - - - - - - Initializes a #GMutex so that it can be used. - -This function is useful to initialize a mutex that has been -allocated on the stack, or as part of a larger structure. -It is not necessary to initialize a mutex that has been -statically allocated. - -|[<!-- language="C" --> - typedef struct { - GMutex m; - ... - } Blob; - -Blob *b; - -b = g_new (Blob, 1); -g_mutex_init (&b->m); -]| - -To undo the effect of g_mutex_init() when a mutex is no longer -needed, use g_mutex_clear(). - -Calling g_mutex_init() on an already initialized #GMutex leads -to undefined behaviour. - - - - - - - an uninitialized #GMutex - - - - - - Locks @mutex. If @mutex is already locked by another thread, the -current thread will block until @mutex is unlocked by the other -thread. - -#GMutex is neither guaranteed to be recursive nor to be -non-recursive. As such, calling g_mutex_lock() on a #GMutex that has -already been locked by the same thread results in undefined behaviour -(including but not limited to deadlocks). - - - - - - - a #GMutex - - - - - - Tries to lock @mutex. If @mutex is already locked by another thread, -it immediately returns %FALSE. Otherwise it locks @mutex and returns -%TRUE. - -#GMutex is neither guaranteed to be recursive nor to be -non-recursive. As such, calling g_mutex_lock() on a #GMutex that has -already been locked by the same thread results in undefined behaviour -(including but not limited to deadlocks or arbitrary return values). - - - %TRUE if @mutex could be locked - - - - - a #GMutex - - - - - - Unlocks @mutex. If another thread is blocked in a g_mutex_lock() -call for @mutex, it will become unblocked and can lock @mutex itself. - -Calling g_mutex_unlock() on a mutex that is not locked by the -current thread leads to undefined behaviour. - - - - - - - a #GMutex - - - - - - - Returns %TRUE if a #GNode is a leaf node. - - - - a #GNode - - - - - Returns %TRUE if a #GNode is the root of a tree. - - - - a #GNode - - - - - Determines the number of elements in an array. The array must be -declared so the compiler knows its size at compile-time; this -macro will not work on an array allocated on the heap, only static -arrays or arrays on the stack. - - - - the array - - - - - The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. - - - contains the actual data of the node. - - - - points to the node's next sibling (a sibling is another - #GNode with the same parent). - - - - points to the node's previous sibling. - - - - points to the parent of the #GNode, or is %NULL if the - #GNode is the root of the tree. - - - - points to the first child of the #GNode. The other - children are accessed by using the @next pointer of each - child. - - - - Gets the position of the first child of a #GNode -which contains the given data. - - - the index of the child of @node which contains - @data, or -1 if the data is not found - - - - - a #GNode - - - - the data to find - - - - - - Gets the position of a #GNode with respect to its siblings. -@child must be a child of @node. The first child is numbered 0, -the second 1, and so on. - - - the position of @child with respect to its siblings - - - - - a #GNode - - - - a child of @node - - - - - - Calls a function for each of the children of a #GNode. Note that it -doesn't descend beneath the child nodes. @func must not do anything -that would modify the structure of the tree. - - - - - - - a #GNode - - - - which types of children are to be visited, one of - %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - - - - the function to call for each visited node - - - - user data to pass to the function - - - - - - Recursively copies a #GNode (but does not deep-copy the data inside the -nodes, see g_node_copy_deep() if you need that). - - - a new #GNode containing the same data pointers - - - - - a #GNode - - - - - - Recursively copies a #GNode and its data. - - - a new #GNode containing copies of the data in @node. - - - - - a #GNode - - - - the function which is called to copy the data inside each node, - or %NULL to use the original data. - - - - data to pass to @copy_func - - - - - - Gets the depth of a #GNode. - -If @node is %NULL the depth is 0. The root node has a depth of 1. -For the children of the root node the depth is 2. And so on. - - - the depth of the #GNode - - - - - a #GNode - - - - - - Removes @root and its children from the tree, freeing any memory -allocated. - - - - - - - the root of the tree/subtree to destroy - - - - - - Finds a #GNode in a tree. - - - the found #GNode, or %NULL if the data is not found - - - - - the root #GNode of the tree to search - - - - the order in which nodes are visited - %G_IN_ORDER, - %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER - - - - which types of children are to be searched, one of - %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - - - - the data to find - - - - - - Finds the first child of a #GNode with the given data. - - - the found child #GNode, or %NULL if the data is not found - - - - - a #GNode - - - - which types of children are to be searched, one of - %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - - - - the data to find - - - - - - Gets the first sibling of a #GNode. -This could possibly be the node itself. - - - the first sibling of @node - - - - - a #GNode - - - - - - Gets the root of a tree. - - - the root of the tree - - - - - a #GNode - - - - - - Inserts a #GNode beneath the parent at the given position. - - - the inserted #GNode - - - - - the #GNode to place @node under - - - - the position to place @node at, with respect to its siblings - If position is -1, @node is inserted as the last child of @parent - - - - the #GNode to insert - - - - - - Inserts a #GNode beneath the parent after the given sibling. - - - the inserted #GNode - - - - - the #GNode to place @node under - - - - the sibling #GNode to place @node after. - If sibling is %NULL, the node is inserted as the first child of @parent. - - - - the #GNode to insert - - - - - - Inserts a #GNode beneath the parent before the given sibling. - - - the inserted #GNode - - - - - the #GNode to place @node under - - - - the sibling #GNode to place @node before. - If sibling is %NULL, the node is inserted as the last child of @parent. - - - - the #GNode to insert - - - - - - Returns %TRUE if @node is an ancestor of @descendant. -This is true if node is the parent of @descendant, -or if node is the grandparent of @descendant etc. - - - %TRUE if @node is an ancestor of @descendant - - - - - a #GNode - - - - a #GNode - - - - - - Gets the last child of a #GNode. - - - the last child of @node, or %NULL if @node has no children - - - - - a #GNode (must not be %NULL) - - - - - - Gets the last sibling of a #GNode. -This could possibly be the node itself. - - - the last sibling of @node - - - - - a #GNode - - - - - - Gets the maximum height of all branches beneath a #GNode. -This is the maximum distance from the #GNode to all leaf nodes. - -If @root is %NULL, 0 is returned. If @root has no children, -1 is returned. If @root has children, 2 is returned. And so on. - - - the maximum height of the tree beneath @root - - - - - a #GNode - - - - - - Gets the number of children of a #GNode. - - - the number of children of @node - - - - - a #GNode - - - - - - Gets the number of nodes in a tree. - - - the number of nodes in the tree - - - - - a #GNode - - - - which types of children are to be counted, one of - %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - - - - - - Gets a child of a #GNode, using the given index. -The first child is at index 0. If the index is -too big, %NULL is returned. - - - the child of @node at index @n - - - - - a #GNode - - - - the index of the desired child - - - - - - Inserts a #GNode as the first child of the given parent. - - - the inserted #GNode - - - - - the #GNode to place the new #GNode under - - - - the #GNode to insert - - - - - - Reverses the order of the children of a #GNode. -(It doesn't change the order of the grandchildren.) - - - - - - - a #GNode. - - - - - - Traverses a tree starting at the given root #GNode. -It calls the given function for each node visited. -The traversal can be halted at any point by returning %TRUE from @func. -@func must not do anything that would modify the structure of the tree. - - - - - - - the root #GNode of the tree to traverse - - - - the order in which nodes are visited - %G_IN_ORDER, - %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. - - - - which types of children are to be visited, one of - %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - - - - the maximum depth of the traversal. Nodes below this - depth will not be visited. If max_depth is -1 all nodes in - the tree are visited. If depth is 1, only the root is visited. - If depth is 2, the root and its children are visited. And so on. - - - - the function to call for each visited #GNode - - - - user data to pass to the function - - - - - - Unlinks a #GNode from a tree, resulting in two separate trees. - - - - - - - the #GNode to unlink, which becomes the root of a new tree - - - - - - Creates a new #GNode containing the given data. -Used to create the first node in a tree. - - - a new #GNode - - - - - the data of the new node - - - - - - - Specifies the type of function passed to g_node_children_foreach(). -The function is called with each child node, together with the user -data passed to g_node_children_foreach(). - - - - - - - a #GNode. - - - - user data passed to g_node_children_foreach(). - - - - - - Specifies the type of function passed to g_node_traverse(). The -function is called with each of the nodes visited, together with the -user data passed to g_node_traverse(). If the function returns -%TRUE, then the traversal is stopped. - - - %TRUE to stop the traversal. - - - - - a #GNode. - - - - user data passed to g_node_traverse(). - - - - - - Defines how a Unicode string is transformed in a canonical -form, standardizing such issues as whether a character with -an accent is represented as a base character and combining -accent or as a single precomposed character. Unicode strings -should generally be normalized before comparing them. - - - standardize differences that do not affect the - text content, such as the above-mentioned accent representation - - - another name for %G_NORMALIZE_DEFAULT - - - like %G_NORMALIZE_DEFAULT, but with - composed forms rather than a maximally decomposed form - - - another name for %G_NORMALIZE_DEFAULT_COMPOSE - - - beyond %G_NORMALIZE_DEFAULT also standardize the - "compatibility" characters in Unicode, such as SUPERSCRIPT THREE - to the standard forms (in this case DIGIT THREE). Formatting - information may be lost but for most text operations such - characters should be considered the same - - - another name for %G_NORMALIZE_ALL - - - like %G_NORMALIZE_ALL, but with composed - forms rather than a maximally decomposed form - - - another name for %G_NORMALIZE_ALL_COMPOSE - - - - Error codes returned by functions converting a string to a number. - - - String was not a valid number. - - - String was a number, but out of bounds. - - - - If a long option in the main group has this name, it is not treated as a -regular option. Instead it collects all non-option arguments which would -otherwise be left in `argv`. The option must be of type -%G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY -or %G_OPTION_ARG_FILENAME_ARRAY. - - -Using #G_OPTION_REMAINING instead of simply scanning `argv` -for leftover arguments has the advantage that GOption takes care of -necessary encoding conversions for strings or filenames. - - - - - A #GOnce struct controls a one-time initialization function. Any -one-time initialization function must have its own unique #GOnce -struct. - - - the status of the #GOnce - - - - the value returned by the call to the function, if @status - is %G_ONCE_STATUS_READY - - - - - - - - - - - - - - - - - - - - - Function to be called when starting a critical initialization -section. The argument @location must point to a static -0-initialized variable that will be set to a value other than 0 at -the end of the initialization section. In combination with -g_once_init_leave() and the unique address @value_location, it can -be ensured that an initialization section will be executed only once -during a program's life time, and that concurrent threads are -blocked until initialization completed. To be used in constructs -like this: - -|[<!-- language="C" --> - static gsize initialization_value = 0; - - if (g_once_init_enter (&initialization_value)) - { - gsize setup_value = 42; // initialization code here - - g_once_init_leave (&initialization_value, setup_value); - } - - // use initialization_value here -]| - - - %TRUE if the initialization section should be entered, - %FALSE and blocks otherwise - - - - - location of a static initializable variable - containing 0 - - - - - - Counterpart to g_once_init_enter(). Expects a location of a static -0-initialized initialization variable, and an initialization value -other than 0. Sets the variable to the initialization value, and -releases concurrent threads blocking in g_once_init_enter() on this -initialization variable. - - - - - - - location of a static initializable variable - containing 0 - - - - new non-0 value for *@value_location - - - - - - - The possible statuses of a one-time initialization function -controlled by a #GOnce struct. - - - the function has not been called yet. - - - the function call is currently in progress. - - - the function has been called. - - - - The #GOptionArg enum values determine which type of extra argument the -options expect to find. If an option expects an extra argument, it can -be specified in several ways; with a short option: `-x arg`, with a long -option: `--name arg` or combined in a single argument: `--name=arg`. - - - No extra argument. This is useful for simple flags. - - - The option takes a UTF-8 string argument. - - - The option takes an integer argument. - - - The option provides a callback (of type - #GOptionArgFunc) to parse the extra argument. - - - The option takes a filename as argument, which will - be in the GLib filename encoding rather than UTF-8. - - - The option takes a string argument, multiple - uses of the option are collected into an array of strings. - - - The option takes a filename as argument, - multiple uses of the option are collected into an array of strings. - - - The option takes a double argument. The argument - can be formatted either for the user's locale or for the "C" locale. - Since 2.12 - - - The option takes a 64-bit integer. Like - %G_OPTION_ARG_INT but for larger numbers. The number can be in - decimal base, or in hexadecimal (when prefixed with `0x`, for - example, `0xffffffff`). Since 2.12 - - - - The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK -options. - - - %TRUE if the option was successfully parsed, %FALSE if an error - occurred, in which case @error should be set with g_set_error() - - - - - The name of the option being parsed. This will be either a - single dash followed by a single letter (for a short name) or two dashes - followed by a long option name. - - - - The value to be parsed. - - - - User data added to the #GOptionGroup containing the option when it - was created with g_option_group_new() - - - - - - A `GOptionContext` struct defines which options -are accepted by the commandline option parser. The struct has only private -fields and should not be directly accessed. - - - Adds a #GOptionGroup to the @context, so that parsing with @context -will recognize the options in the group. Note that this will take -ownership of the @group and thus the @group should not be freed. - - - - - - - a #GOptionContext - - - - the group to add - - - - - - A convenience function which creates a main group if it doesn't -exist, adds the @entries to it and sets the translation domain. - - - - - - - a #GOptionContext - - - - a %NULL-terminated array of #GOptionEntrys - - - - - - a translation domain to use for translating - the `--help` output for the options in @entries - with gettext(), or %NULL - - - - - - Frees context and all the groups which have been -added to it. - -Please note that parsed arguments need to be freed separately (see -#GOptionEntry). - - - - - - - a #GOptionContext - - - - - - Returns the description. See g_option_context_set_description(). - - - the description - - - - - a #GOptionContext - - - - - - Returns a formatted, translated help text for the given context. -To obtain the text produced by `--help`, call -`g_option_context_get_help (context, TRUE, NULL)`. -To obtain the text produced by `--help-all`, call -`g_option_context_get_help (context, FALSE, NULL)`. -To obtain the help text for an option group, call -`g_option_context_get_help (context, FALSE, group)`. - - - A newly allocated string containing the help text - - - - - a #GOptionContext - - - - if %TRUE, only include the main group - - - - the #GOptionGroup to create help for, or %NULL - - - - - - Returns whether automatic `--help` generation -is turned on for @context. See g_option_context_set_help_enabled(). - - - %TRUE if automatic help generation is turned on. - - - - - a #GOptionContext - - - - - - Returns whether unknown options are ignored or not. See -g_option_context_set_ignore_unknown_options(). - - - %TRUE if unknown options are ignored. - - - - - a #GOptionContext - - - - - - Returns a pointer to the main group of @context. - - - the main group of @context, or %NULL if - @context doesn't have a main group. Note that group belongs to - @context and should not be modified or freed. - - - - - a #GOptionContext - - - - - - Returns whether strict POSIX code is enabled. - -See g_option_context_set_strict_posix() for more information. - - - %TRUE if strict POSIX is enabled, %FALSE otherwise. - - - - - a #GOptionContext - - - - - - Returns the summary. See g_option_context_set_summary(). - - - the summary - - - - - a #GOptionContext - - - - - - Parses the command line arguments, recognizing options -which have been added to @context. A side-effect of -calling this function is that g_set_prgname() will be -called. - -If the parsing is successful, any parsed arguments are -removed from the array and @argc and @argv are updated -accordingly. A '--' option is stripped from @argv -unless there are unparsed options before and after it, -or some of the options after it start with '-'. In case -of an error, @argc and @argv are left unmodified. - -If automatic `--help` support is enabled -(see g_option_context_set_help_enabled()), and the -@argv array contains one of the recognized help options, -this function will produce help output to stdout and -call `exit (0)`. - -Note that function depends on the [current locale][setlocale] for -automatic character set conversion of string and filename -arguments. - - - %TRUE if the parsing was successful, - %FALSE if an error occurred - - - - - a #GOptionContext - - - - a pointer to the number of command line arguments - - - - a pointer to the array of command line arguments - - - - - - - - Parses the command line arguments. - -This function is similar to g_option_context_parse() except that it -respects the normal memory rules when dealing with a strv instead of -assuming that the passed-in array is the argv of the main function. - -In particular, strings that are removed from the arguments list will -be freed using g_free(). - -On Windows, the strings are expected to be in UTF-8. This is in -contrast to g_option_context_parse() which expects them to be in the -system codepage, which is how they are passed as @argv to main(). -See g_win32_get_command_line() for a solution. - -This function is useful if you are trying to use #GOptionContext with -#GApplication. - - - %TRUE if the parsing was successful, - %FALSE if an error occurred - - - - - a #GOptionContext - - - - a pointer - to the command line arguments (which must be in UTF-8 on Windows). - Starting with GLib 2.62, @arguments can be %NULL, which matches - g_option_context_parse(). - - - - - - - - Adds a string to be displayed in `--help` output after the list -of options. This text often includes a bug reporting address. - -Note that the summary is translated (see -g_option_context_set_translate_func()). - - - - - - - a #GOptionContext - - - - a string to be shown in `--help` output - after the list of options, or %NULL - - - - - - Enables or disables automatic generation of `--help` output. -By default, g_option_context_parse() recognizes `--help`, `-h`, -`-?`, `--help-all` and `--help-groupname` and creates suitable -output to stdout. - - - - - - - a #GOptionContext - - - - %TRUE to enable `--help`, %FALSE to disable it - - - - - - Sets whether to ignore unknown options or not. If an argument is -ignored, it is left in the @argv array after parsing. By default, -g_option_context_parse() treats unknown options as error. - -This setting does not affect non-option arguments (i.e. arguments -which don't start with a dash). But note that GOption cannot reliably -determine whether a non-option belongs to a preceding unknown option. - - - - - - - a #GOptionContext - - - - %TRUE to ignore unknown options, %FALSE to produce - an error when unknown options are met - - - - - - Sets a #GOptionGroup as main group of the @context. -This has the same effect as calling g_option_context_add_group(), -the only difference is that the options in the main group are -treated differently when generating `--help` output. - - - - - - - a #GOptionContext - - - - the group to set as main group - - - - - - Sets strict POSIX mode. - -By default, this mode is disabled. - -In strict POSIX mode, the first non-argument parameter encountered -(eg: filename) terminates argument processing. Remaining arguments -are treated as non-options and are not attempted to be parsed. - -If strict POSIX mode is disabled then parsing is done in the GNU way -where option arguments can be freely mixed with non-options. - -As an example, consider "ls foo -l". With GNU style parsing, this -will list "foo" in long mode. In strict POSIX style, this will list -the files named "foo" and "-l". - -It may be useful to force strict POSIX mode when creating "verb -style" command line tools. For example, the "gsettings" command line -tool supports the global option "--schemadir" as well as many -subcommands ("get", "set", etc.) which each have their own set of -arguments. Using strict POSIX mode will allow parsing the global -options up to the verb name while leaving the remaining options to be -parsed by the relevant subcommand (which can be determined by -examining the verb name, which should be present in argv[1] after -parsing). - - - - - - - a #GOptionContext - - - - the new value - - - - - - Adds a string to be displayed in `--help` output before the list -of options. This is typically a summary of the program functionality. - -Note that the summary is translated (see -g_option_context_set_translate_func() and -g_option_context_set_translation_domain()). - - - - - - - a #GOptionContext - - - - a string to be shown in `--help` output - before the list of options, or %NULL - - - - - - Sets the function which is used to translate the contexts -user-visible strings, for `--help` output. If @func is %NULL, -strings are not translated. - -Note that option groups have their own translation functions, -this function only affects the @parameter_string (see g_option_context_new()), -the summary (see g_option_context_set_summary()) and the description -(see g_option_context_set_description()). - -If you are using gettext(), you only need to set the translation -domain, see g_option_context_set_translation_domain(). - - - - - - - a #GOptionContext - - - - the #GTranslateFunc, or %NULL - - - - user data to pass to @func, or %NULL - - - - a function which gets called to free @data, or %NULL - - - - - - A convenience function to use gettext() for translating -user-visible strings. - - - - - - - a #GOptionContext - - - - the domain to use - - - - - - Creates a new option context. - -The @parameter_string can serve multiple purposes. It can be used -to add descriptions for "rest" arguments, which are not parsed by -the #GOptionContext, typically something like "FILES" or -"FILE1 FILE2...". If you are using #G_OPTION_REMAINING for -collecting "rest" arguments, GLib handles this automatically by -using the @arg_description of the corresponding #GOptionEntry in -the usage summary. - -Another usage is to give a short summary of the program -functionality, like " - frob the strings", which will be displayed -in the same line as the usage. For a longer description of the -program functionality that should be displayed as a paragraph -below the usage line, use g_option_context_set_summary(). - -Note that the @parameter_string is translated using the -function set with g_option_context_set_translate_func(), so -it should normally be passed untranslated. - - - a newly created #GOptionContext, which must be - freed with g_option_context_free() after use. - - - - - a string which is displayed in - the first line of `--help` output, after the usage summary - `programname [OPTION...]` - - - - - - - A GOptionEntry struct defines a single option. To have an effect, they -must be added to a #GOptionGroup with g_option_context_add_main_entries() -or g_option_group_add_entries(). - - - The long name of an option can be used to specify it - in a commandline as `--long_name`. Every option must have a - long name. To resolve conflicts if multiple option groups contain - the same long name, it is also possible to specify the option as - `--groupname-long_name`. - - - - If an option has a short name, it can be specified - `-short_name` in a commandline. @short_name must be a printable - ASCII character different from '-', or zero if the option has no - short name. - - - - Flags from #GOptionFlags - - - - The type of the option, as a #GOptionArg - - - - If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data - must point to a #GOptionArgFunc callback function, which will be - called to handle the extra argument. Otherwise, @arg_data is a - pointer to a location to store the value, the required type of - the location depends on the @arg type: - - %G_OPTION_ARG_NONE: %gboolean - - %G_OPTION_ARG_STRING: %gchar* - - %G_OPTION_ARG_INT: %gint - - %G_OPTION_ARG_FILENAME: %gchar* - - %G_OPTION_ARG_STRING_ARRAY: %gchar** - - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** - - %G_OPTION_ARG_DOUBLE: %gdouble - If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, - the location will contain a newly allocated string if the option - was given. That string needs to be freed by the callee using g_free(). - Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or - %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). - - - - the description for the option in `--help` - output. The @description is translated using the @translate_func - of the group, see g_option_group_set_translation_domain(). - - - - The placeholder to use for the extra argument parsed - by the option in `--help` output. The @arg_description is translated - using the @translate_func of the group, see - g_option_group_set_translation_domain(). - - - - - Error codes returned by option parsing. - - - An option was not known to the parser. - This error will only be reported, if the parser hasn't been instructed - to ignore unknown options, see g_option_context_set_ignore_unknown_options(). - - - A value couldn't be parsed. - - - A #GOptionArgFunc callback failed. - - - - The type of function to be used as callback when a parse error occurs. - - - - - - - The active #GOptionContext - - - - The group to which the function belongs - - - - User data added to the #GOptionGroup containing the option when it - was created with g_option_group_new() - - - - - - Flags which modify individual options. - - - No flags. Since: 2.42. - - - The option doesn't appear in `--help` output. - - - The option appears in the main section of the - `--help` output, even if it is defined in a group. - - - For options of the %G_OPTION_ARG_NONE kind, this - flag indicates that the sense of the option is reversed. - - - For options of the %G_OPTION_ARG_CALLBACK kind, - this flag indicates that the callback does not take any argument - (like a %G_OPTION_ARG_NONE option). Since 2.8 - - - For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument should be passed to the - callback in the GLib filename encoding rather than UTF-8. Since 2.8 - - - For options of the %G_OPTION_ARG_CALLBACK - kind, this flag indicates that the argument supply is optional. - If no argument is given then data of %GOptionParseFunc will be - set to NULL. Since 2.8 - - - This flag turns off the automatic conflict - resolution which prefixes long option names with `groupname-` if - there is a conflict. This option should only be used in situations - where aliasing is necessary to model some legacy commandline interface. - It is not safe to use this option, unless all option groups are under - your direct control. Since 2.8. - - - - A `GOptionGroup` struct defines the options in a single -group. The struct has only private fields and should not be directly accessed. - -All options in a group share the same translation function. Libraries which -need to parse commandline options are expected to provide a function for -getting a `GOptionGroup` holding their options, which -the application can then add to its #GOptionContext. - - - Creates a new #GOptionGroup. - - - a newly created option group. It should be added - to a #GOptionContext or freed with g_option_group_unref(). - - - - - the name for the option group, this is used to provide - help for the options in this group with `--help-`@name - - - - a description for this group to be shown in - `--help`. This string is translated using the translation - domain or translation function of the group - - - - a description for the `--help-`@name option. - This string is translated using the translation domain or translation function - of the group - - - - user data that will be passed to the pre- and post-parse hooks, - the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL - - - - a function that will be called to free @user_data, or %NULL - - - - - - Adds the options specified in @entries to @group. - - - - - - - a #GOptionGroup - - - - a %NULL-terminated array of #GOptionEntrys - - - - - - - - Frees a #GOptionGroup. Note that you must not free groups -which have been added to a #GOptionContext. - Use g_option_group_unref() instead. - - - - - - - a #GOptionGroup - - - - - - Increments the reference count of @group by one. - - - a #GOptionGroup - - - - - a #GOptionGroup - - - - - - Associates a function with @group which will be called -from g_option_context_parse() when an error occurs. - -Note that the user data to be passed to @error_func can be -specified when constructing the group with g_option_group_new(). - - - - - - - a #GOptionGroup - - - - a function to call when an error occurs - - - - - - Associates two functions with @group which will be called -from g_option_context_parse() before the first option is parsed -and after the last option has been parsed, respectively. - -Note that the user data to be passed to @pre_parse_func and -@post_parse_func can be specified when constructing the group -with g_option_group_new(). - - - - - - - a #GOptionGroup - - - - a function to call before parsing, or %NULL - - - - a function to call after parsing, or %NULL - - - - - - Sets the function which is used to translate user-visible strings, -for `--help` output. Different groups can use different -#GTranslateFuncs. If @func is %NULL, strings are not translated. - -If you are using gettext(), you only need to set the translation -domain, see g_option_group_set_translation_domain(). - - - - - - - a #GOptionGroup - - - - the #GTranslateFunc, or %NULL - - - - user data to pass to @func, or %NULL - - - - a function which gets called to free @data, or %NULL - - - - - - A convenience function to use gettext() for translating -user-visible strings. - - - - - - - a #GOptionGroup - - - - the domain to use - - - - - - Decrements the reference count of @group by one. -If the reference count drops to 0, the @group will be freed. -and all memory allocated by the @group is released. - - - - - - - a #GOptionGroup - - - - - - - The type of function that can be called before and after parsing. - - - %TRUE if the function completed successfully, %FALSE if an error - occurred, in which case @error should be set with g_set_error() - - - - - The active #GOptionContext - - - - The group to which the function belongs - - - - User data added to the #GOptionGroup containing the option when it - was created with g_option_group_new() - - - - - - Specifies one of the possible types of byte order -(currently unused). See #G_BYTE_ORDER. - - - - - The value of pi (ratio of circle's circumference to its diameter). - - - - - A format specifier that can be used in printf()-style format strings -when printing a #GPid. - - - - - Pi divided by 2. - - - - - Pi divided by 4. - - - - - A format specifier that can be used in printf()-style format strings -when printing the @fd member of a #GPollFD. - - - - - Use this for default priority event sources. - -In GLib this priority is used when adding timeout functions -with g_timeout_add(). In GDK this priority is used for events -from the X server. - - - - - Use this for default priority idle functions. - -In GLib this priority is used when adding idle functions with -g_idle_add(). - - - - - Use this for high priority event sources. - -It is not used within GLib or GTK+. - - - - - Use this for high priority idle functions. - -GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, -and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is -done to ensure that any pending resizes are processed before any -pending redraws, so that widgets are not redrawn twice unnecessarily.) - - - - - Use this for very low priority background tasks. - -It is not used within GLib or GTK+. - - - - - A macro to assist with the static initialisation of a #GPrivate. - -This macro is useful for the case that a #GDestroyNotify function -should be associated with the key. This is needed when the key will be -used to point at memory that should be deallocated when the thread -exits. - -Additionally, the #GDestroyNotify will also be called on the previous -value stored in the key when g_private_replace() is used. - -If no #GDestroyNotify is needed, then use of this macro is not -required -- if the #GPrivate is declared in static scope then it will -be properly initialised by default (ie: to all zeros). See the -examples below. - -|[<!-- language="C" --> -static GPrivate name_key = G_PRIVATE_INIT (g_free); - -// return value should not be freed -const gchar * -get_local_name (void) -{ - return g_private_get (&name_key); -} - -void -set_local_name (const gchar *name) -{ - g_private_replace (&name_key, g_strdup (name)); -} - - -static GPrivate count_key; // no free function - -gint -get_local_count (void) -{ - return GPOINTER_TO_INT (g_private_get (&count_key)); -} - -void -set_local_count (gint count) -{ - g_private_set (&count_key, GINT_TO_POINTER (count)); -} -]| - - - - a #GDestroyNotify - - - - - A GPatternSpec struct is the 'compiled' form of a pattern. This -structure is opaque and its fields cannot be accessed directly. - - - Compares two compiled pattern specs and returns whether they will -match the same set of strings. - - - Whether the compiled patterns are equal - - - - - a #GPatternSpec - - - - another #GPatternSpec - - - - - - Frees the memory allocated for the #GPatternSpec. - - - - - - - a #GPatternSpec - - - - - - Compiles a pattern to a #GPatternSpec. - - - a newly-allocated #GPatternSpec - - - - - a zero-terminated UTF-8 encoded string - - - - - - - Represents a file descriptor, which events to poll for, and which events -occurred. - - - the file descriptor to poll (or a HANDLE on Win32) - - - - a bitwise combination from #GIOCondition, specifying which - events should be polled for. Typically for reading from a file - descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and - for writing you would use %G_IO_OUT | %G_IO_ERR. - - - - a bitwise combination of flags from #GIOCondition, returned - from the poll() function to indicate which events occurred. - - - - - Specifies the type of function passed to g_main_context_set_poll_func(). -The semantics of the function should match those of the poll() system call. - - - the number of #GPollFD elements which have events or errors - reported, or -1 if an error occurred. - - - - - an array of #GPollFD elements - - - - the number of elements in @ufds - - - - the maximum time to wait for an event of the file descriptors. - A negative value indicates an infinite timeout. - - - - - - Specifies the type of the print handler functions. -These are called with the complete formatted string to output. - - - - - - - the message to output - - - - - - The #GPrivate struct is an opaque data structure to represent a -thread-local data key. It is approximately equivalent to the -pthread_setspecific()/pthread_getspecific() APIs on POSIX and to -TlsSetValue()/TlsGetValue() on Windows. - -If you don't already know why you might want this functionality, -then you probably don't need it. - -#GPrivate is a very limited resource (as far as 128 per program, -shared between all libraries). It is also not possible to destroy a -#GPrivate after it has been used. As such, it is only ever acceptable -to use #GPrivate in static scope, and even then sparingly so. - -See G_PRIVATE_INIT() for a couple of examples. - -The #GPrivate structure should be considered opaque. It should only -be accessed via the g_private_ functions. - - - - - - - - - - - - - - Returns the current value of the thread local variable @key. - -If the value has not yet been set in this thread, %NULL is returned. -Values are never copied between threads (when a new thread is -created, for example). - - - the thread-local value - - - - - a #GPrivate - - - - - - Sets the thread local variable @key to have the value @value in the -current thread. - -This function differs from g_private_set() in the following way: if -the previous value was non-%NULL then the #GDestroyNotify handler for -@key is run on it. - - - - - - - a #GPrivate - - - - the new value - - - - - - Sets the thread local variable @key to have the value @value in the -current thread. - -This function differs from g_private_replace() in the following way: -the #GDestroyNotify for @key is not called on the old value. - - - - - - - a #GPrivate - - - - the new value - - - - - - - Contains the public fields of a pointer array. - - - points to the array of pointers, which may be moved when the - array grows - - - - number of pointers in the array - - - - Adds a pointer to the end of the pointer array. The array will grow -in size automatically if necessary. - - - - - - - a #GPtrArray - - - - - - the pointer to add - - - - - - Makes a full (deep) copy of a #GPtrArray. - -@func, as a #GCopyFunc, takes two arguments, the data to be copied -and a @user_data pointer. On common processor architectures, it's safe to -pass %NULL as @user_data if the copy function takes only one argument. You -may get compiler warnings from this though if compiling with GCC’s -`-Wcast-function-type` warning. - -If @func is %NULL, then only the pointers (and not what they are -pointing to) are copied to the new #GPtrArray. - -The copy of @array will have the same #GDestroyNotify for its elements as -@array. - - - a deep copy of the initial #GPtrArray. - - - - - - - #GPtrArray to duplicate - - - - - - a copy function used to copy every element in the array - - - - user data passed to the copy function @func, or %NULL - - - - - - Adds all pointers of @array to the end of the array @array_to_extend. -The array will grow in size automatically if needed. @array_to_extend is -modified in-place. - -@func, as a #GCopyFunc, takes two arguments, the data to be copied -and a @user_data pointer. On common processor architectures, it's safe to -pass %NULL as @user_data if the copy function takes only one argument. You -may get compiler warnings from this though if compiling with GCC’s -`-Wcast-function-type` warning. - -If @func is %NULL, then only the pointers (and not what they are -pointing to) are copied to the new #GPtrArray. - - - - - - - a #GPtrArray. - - - - - - a #GPtrArray to add to the end of @array_to_extend. - - - - - - a copy function used to copy every element in the array - - - - user data passed to the copy function @func, or %NULL - - - - - - Adds all the pointers in @array to the end of @array_to_extend, transferring -ownership of each element from @array to @array_to_extend and modifying -@array_to_extend in-place. @array is then freed. - -As with g_ptr_array_free(), @array will be destroyed if its reference count -is 1. If its reference count is higher, it will be decremented and the -length of @array set to zero. - - - - - - - a #GPtrArray. - - - - - - a #GPtrArray to add to the end of - @array_to_extend. - - - - - - - - Checks whether @needle exists in @haystack. If the element is found, %TRUE is -returned and the element’s index is returned in @index_ (if non-%NULL). -Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists -multiple times in @haystack, the index of the first instance is returned. - -This does pointer comparisons only. If you want to use more complex equality -checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). - - - %TRUE if @needle is one of the elements of @haystack - - - - - pointer array to be searched - - - - - - pointer to look for - - - - return location for the index of - the element, if found - - - - - - Checks whether @needle exists in @haystack, using the given @equal_func. -If the element is found, %TRUE is returned and the element’s index is -returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ -is undefined. If @needle exists multiple times in @haystack, the index of -the first instance is returned. - -@equal_func is called with the element from the array as its first parameter, -and @needle as its second parameter. If @equal_func is %NULL, pointer -equality is used. - - - %TRUE if @needle is one of the elements of @haystack - - - - - pointer array to be searched - - - - - - pointer to look for - - - - the function to call for each element, which should - return %TRUE when the desired element is found; or %NULL to use pointer - equality - - - - return location for the index of - the element, if found - - - - - - Calls a function for each element of a #GPtrArray. @func must not -add elements to or remove elements from the array. - - - - - - - a #GPtrArray - - - - - - the function to call for each array element - - - - user data to pass to the function - - - - - - Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE -it frees the memory block holding the elements as well. Pass %FALSE -if you want to free the #GPtrArray wrapper but preserve the -underlying array for use elsewhere. If the reference count of @array -is greater than one, the #GPtrArray wrapper is preserved but the -size of @array will be set to zero. - -If array contents point to dynamically-allocated memory, they should -be freed separately if @free_seg is %TRUE and no #GDestroyNotify -function has been set for @array. - -This function is not thread-safe. If using a #GPtrArray from multiple -threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() -functions. - - - the pointer array if @free_seg is %FALSE, otherwise %NULL. - The pointer array should be freed using g_free(). - - - - - a #GPtrArray - - - - - - if %TRUE the actual pointer array is freed as well - - - - - - Inserts an element into the pointer array at the given index. The -array will grow in size automatically if necessary. - - - - - - - a #GPtrArray - - - - - - the index to place the new element at, or -1 to append - - - - the pointer to add. - - - - - - Creates a new #GPtrArray with a reference count of 1. - - - the new #GPtrArray - - - - - - - Creates a new #GPtrArray with @reserved_size pointers preallocated -and a reference count of 1. This avoids frequent reallocation, if -you are going to add many pointers to the array. Note however that -the size of the array is still 0. It also set @element_free_func -for freeing each element when the array is destroyed either via -g_ptr_array_unref(), when g_ptr_array_free() is called with -@free_segment set to %TRUE or when removing elements. - - - A new #GPtrArray - - - - - - - number of pointers preallocated - - - - A function to free elements with - destroy @array or %NULL - - - - - - Creates a new #GPtrArray with a reference count of 1 and use -@element_free_func for freeing each element when the array is destroyed -either via g_ptr_array_unref(), when g_ptr_array_free() is called with -@free_segment set to %TRUE or when removing elements. - - - A new #GPtrArray - - - - - - - A function to free elements with - destroy @array or %NULL - - - - - - Atomically increments the reference count of @array by one. -This function is thread-safe and may be called from any thread. - - - The passed in #GPtrArray - - - - - - - a #GPtrArray - - - - - - - - Removes the first occurrence of the given pointer from the pointer -array. The following elements are moved down one place. If @array -has a non-%NULL #GDestroyNotify function it is called for the -removed element. - -It returns %TRUE if the pointer was removed, or %FALSE if the -pointer was not found. - - - %TRUE if the pointer is removed, %FALSE if the pointer - is not found in the array - - - - - a #GPtrArray - - - - - - the pointer to remove - - - - - - Removes the first occurrence of the given pointer from the pointer -array. The last element in the array is used to fill in the space, -so this function does not preserve the order of the array. But it -is faster than g_ptr_array_remove(). If @array has a non-%NULL -#GDestroyNotify function it is called for the removed element. - -It returns %TRUE if the pointer was removed, or %FALSE if the -pointer was not found. - - - %TRUE if the pointer was found in the array - - - - - a #GPtrArray - - - - - - the pointer to remove - - - - - - Removes the pointer at the given index from the pointer array. -The following elements are moved down one place. If @array has -a non-%NULL #GDestroyNotify function it is called for the removed -element. If so, the return value from this function will potentially point -to freed memory (depending on the #GDestroyNotify implementation). - - - the pointer which was removed - - - - - a #GPtrArray - - - - - - the index of the pointer to remove - - - - - - Removes the pointer at the given index from the pointer array. -The last element in the array is used to fill in the space, so -this function does not preserve the order of the array. But it -is faster than g_ptr_array_remove_index(). If @array has a non-%NULL -#GDestroyNotify function it is called for the removed element. If so, the -return value from this function will potentially point to freed memory -(depending on the #GDestroyNotify implementation). - - - the pointer which was removed - - - - - a #GPtrArray - - - - - - the index of the pointer to remove - - - - - - Removes the given number of pointers starting at the given index -from a #GPtrArray. The following elements are moved to close the -gap. If @array has a non-%NULL #GDestroyNotify function it is -called for the removed elements. - - - the @array - - - - - - - a @GPtrArray - - - - - - the index of the first pointer to remove - - - - the number of pointers to remove - - - - - - Sets a function for freeing each element when @array is destroyed -either via g_ptr_array_unref(), when g_ptr_array_free() is called -with @free_segment set to %TRUE or when removing elements. - - - - - - - A #GPtrArray - - - - - - A function to free elements with - destroy @array or %NULL - - - - - - Sets the size of the array. When making the array larger, -newly-added elements will be set to %NULL. When making it smaller, -if @array has a non-%NULL #GDestroyNotify function then it will be -called for the removed elements. - - - - - - - a #GPtrArray - - - - - - the new length of the pointer array - - - - - - Creates a new #GPtrArray with @reserved_size pointers preallocated -and a reference count of 1. This avoids frequent reallocation, if -you are going to add many pointers to the array. Note however that -the size of the array is still 0. - - - the new #GPtrArray - - - - - - - number of pointers preallocated - - - - - - Sorts the array, using @compare_func which should be a qsort()-style -comparison function (returns less than zero for first arg is less -than second arg, zero for equal, greater than zero if irst arg is -greater than second arg). - -Note that the comparison function for g_ptr_array_sort() doesn't -take the pointers from the array as arguments, it takes pointers to -the pointers in the array. Here is a full example of usage: - -|[<!-- language="C" --> -typedef struct -{ - gchar *name; - gint size; -} FileListEntry; - -static gint -sort_filelist (gconstpointer a, gconstpointer b) -{ - const FileListEntry *entry1 = *((FileListEntry **) a); - const FileListEntry *entry2 = *((FileListEntry **) b); - - return g_ascii_strcasecmp (entry1->name, entry2->name); -} - -… -g_autoptr (GPtrArray) file_list = NULL; - -// initialize file_list array and load with many FileListEntry entries -... -// now sort it with -g_ptr_array_sort (file_list, sort_filelist); -]| - -This is guaranteed to be a stable sort since version 2.32. - - - - - - - a #GPtrArray - - - - - - comparison function - - - - - - Like g_ptr_array_sort(), but the comparison function has an extra -user data argument. - -Note that the comparison function for g_ptr_array_sort_with_data() -doesn't take the pointers from the array as arguments, it takes -pointers to the pointers in the array. Here is a full example of use: - -|[<!-- language="C" --> -typedef enum { SORT_NAME, SORT_SIZE } SortMode; - -typedef struct -{ - gchar *name; - gint size; -} FileListEntry; - -static gint -sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data) -{ - gint order; - const SortMode sort_mode = GPOINTER_TO_INT (user_data); - const FileListEntry *entry1 = *((FileListEntry **) a); - const FileListEntry *entry2 = *((FileListEntry **) b); - - switch (sort_mode) - { - case SORT_NAME: - order = g_ascii_strcasecmp (entry1->name, entry2->name); - break; - case SORT_SIZE: - order = entry1->size - entry2->size; - break; - default: - order = 0; - break; - } - return order; -} - -... -g_autoptr (GPtrArray) file_list = NULL; -SortMode sort_mode; - -// initialize file_list array and load with many FileListEntry entries -... -// now sort it with -sort_mode = SORT_NAME; -g_ptr_array_sort_with_data (file_list, - sort_filelist, - GINT_TO_POINTER (sort_mode)); -]| - -This is guaranteed to be a stable sort since version 2.32. - - - - - - - a #GPtrArray - - - - - - comparison function - - - - data to pass to @compare_func - - - - - - Frees the data in the array and resets the size to zero, while -the underlying array is preserved for use elsewhere and returned -to the caller. - -Even if set, the #GDestroyNotify function will never be called -on the current contents of the array and the caller is -responsible for freeing the array elements. - -An example of use: -|[<!-- language="C" --> -g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref); - -// Some part of your application appends a number of chunks to the pointer array. -g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5)); -g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5)); - -… - -// Periodically, the chunks need to be sent as an array-and-length to some -// other part of the program. -GBytes **chunks; -gsize n_chunks; - -chunks = g_ptr_array_steal (chunk_buffer, &n_chunks); -for (gsize i = 0; i < n_chunks; i++) - { - // Do something with each chunk here, and then free them, since - // g_ptr_array_steal() transfers ownership of all the elements and the - // array to the caller. - … - - g_bytes_unref (chunks[i]); - } - -g_free (chunks); - -// After calling g_ptr_array_steal(), the pointer array can be reused for the -// next set of chunks. -g_assert (chunk_buffer->len == 0); -]| - - - the element data, which should be - freed using g_free(). - - - - - a #GPtrArray. - - - - - - pointer to retrieve the number of - elements of the original array - - - - - - Removes the pointer at the given index from the pointer array. -The following elements are moved down one place. The #GDestroyNotify for -@array is *not* called on the removed element; ownership is transferred to -the caller of this function. - - - the pointer which was removed - - - - - a #GPtrArray - - - - - - the index of the pointer to steal - - - - - - Removes the pointer at the given index from the pointer array. -The last element in the array is used to fill in the space, so -this function does not preserve the order of the array. But it -is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is -*not* called on the removed element; ownership is transferred to the caller -of this function. - - - the pointer which was removed - - - - - a #GPtrArray - - - - - - the index of the pointer to steal - - - - - - Atomically decrements the reference count of @array by one. If the -reference count drops to 0, the effect is the same as calling -g_ptr_array_free() with @free_segment set to %TRUE. This function -is thread-safe and may be called from any thread. - - - - - - - A #GPtrArray - - - - - - - - - Contains the public fields of a -[Queue][glib-Double-ended-Queues]. - - - a pointer to the first element of the queue - - - - - - a pointer to the last element of the queue - - - - - - the number of elements in the queue - - - - Removes all the elements in @queue. If queue elements contain -dynamically-allocated memory, they should be freed first. - - - - - - - a #GQueue - - - - - - Convenience method, which frees all the memory used by a #GQueue, -and calls the provided @free_func on each item in the #GQueue. - - - - - - - a pointer to a #GQueue - - - - the function to be called to free memory allocated - - - - - - Copies a @queue. Note that is a shallow copy. If the elements in the -queue consist of pointers to data, the pointers are copied, but the -actual data is not. - - - a copy of @queue - - - - - a #GQueue - - - - - - Removes @link_ from @queue and frees it. - -@link_ must be part of @queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue - - - - - - - - Finds the first link in @queue which contains @data. - - - the first link in @queue which contains @data - - - - - - - a #GQueue - - - - data to find - - - - - - Finds an element in a #GQueue, using a supplied function to find the -desired element. It iterates over the queue, calling the given function -which should return 0 when the desired element is found. The function -takes two gconstpointer arguments, the #GQueue element's data as the -first argument and the given user data as the second argument. - - - the found link, or %NULL if it wasn't found - - - - - - - a #GQueue - - - - user data passed to @func - - - - a #GCompareFunc to call for each element. It should return 0 - when the desired element is found - - - - - - Calls @func for each element in the queue passing @user_data to the -function. - -It is safe for @func to remove the element from @queue, but it must -not modify any part of the queue after that element. - - - - - - - a #GQueue - - - - the function to call for each element's data - - - - user data to pass to @func - - - - - - Frees the memory allocated for the #GQueue. Only call this function -if @queue was created with g_queue_new(). If queue elements contain -dynamically-allocated memory, they should be freed first. - -If queue elements contain dynamically-allocated memory, you should -either use g_queue_free_full() or free them manually first. - - - - - - - a #GQueue - - - - - - Convenience method, which frees all the memory used by a #GQueue, -and calls the specified destroy function on every element's data. - -@free_func should not modify the queue (eg, by removing the freed -element from it). - - - - - - - a pointer to a #GQueue - - - - the function to be called to free each element's data - - - - - - Returns the number of items in @queue. - - - the number of items in @queue - - - - - a #GQueue - - - - - - Returns the position of the first element in @queue which contains @data. - - - the position of the first element in @queue which - contains @data, or -1 if no element in @queue contains @data - - - - - a #GQueue - - - - the data to find - - - - - - A statically-allocated #GQueue must be initialized with this function -before it can be used. Alternatively you can initialize it with -#G_QUEUE_INIT. It is not necessary to initialize queues created with -g_queue_new(). - - - - - - - an uninitialized #GQueue - - - - - - Inserts @data into @queue after @sibling. - -@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the -data at the head of the queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue, or %NULL to - push at the head of the queue. - - - - - - the data to insert - - - - - - Inserts @link_ into @queue after @sibling. - -@sibling must be part of @queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue, or %NULL to - push at the head of the queue. - - - - - - a #GList link to insert which must not be part of any other list. - - - - - - - - Inserts @data into @queue before @sibling. - -@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the -data at the tail of the queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue, or %NULL to - push at the tail of the queue. - - - - - - the data to insert - - - - - - Inserts @link_ into @queue before @sibling. - -@sibling must be part of @queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue, or %NULL to - push at the tail of the queue. - - - - - - a #GList link to insert which must not be part of any other list. - - - - - - - - Inserts @data into @queue using @func to determine the new position. - - - - - - - a #GQueue - - - - the data to insert - - - - the #GCompareDataFunc used to compare elements in the queue. It is - called with two elements of the @queue and @user_data. It should - return 0 if the elements are equal, a negative value if the first - element comes before the second, and a positive value if the second - element comes before the first. - - - - user data passed to @func - - - - - - Returns %TRUE if the queue is empty. - - - %TRUE if the queue is empty - - - - - a #GQueue. - - - - - - Returns the position of @link_ in @queue. - - - the position of @link_, or -1 if the link is - not part of @queue - - - - - a #GQueue - - - - a #GList link - - - - - - - - Returns the first element of the queue. - - - the data of the first element in the queue, or %NULL - if the queue is empty - - - - - a #GQueue - - - - - - Returns the first link in @queue. - - - the first link in @queue, or %NULL if @queue is empty - - - - - - - a #GQueue - - - - - - Returns the @n'th element of @queue. - - - the data for the @n'th element of @queue, - or %NULL if @n is off the end of @queue - - - - - a #GQueue - - - - the position of the element - - - - - - Returns the link at the given position - - - the link at the @n'th position, or %NULL - if @n is off the end of the list - - - - - - - a #GQueue - - - - the position of the link - - - - - - Returns the last element of the queue. - - - the data of the last element in the queue, or %NULL - if the queue is empty - - - - - a #GQueue - - - - - - Returns the last link in @queue. - - - the last link in @queue, or %NULL if @queue is empty - - - - - - - a #GQueue - - - - - - Removes the first element of the queue and returns its data. - - - the data of the first element in the queue, or %NULL - if the queue is empty - - - - - a #GQueue - - - - - - Removes and returns the first element of the queue. - - - the #GList element at the head of the queue, or %NULL - if the queue is empty - - - - - - - a #GQueue - - - - - - Removes the @n'th element of @queue and returns its data. - - - the element's data, or %NULL if @n is off the end of @queue - - - - - a #GQueue - - - - the position of the element - - - - - - Removes and returns the link at the given position. - - - the @n'th link, or %NULL if @n is off the end of @queue - - - - - - - a #GQueue - - - - the link's position - - - - - - Removes the last element of the queue and returns its data. - - - the data of the last element in the queue, or %NULL - if the queue is empty - - - - - a #GQueue - - - - - - Removes and returns the last element of the queue. - - - the #GList element at the tail of the queue, or %NULL - if the queue is empty - - - - - - - a #GQueue - - - - - - Adds a new element at the head of the queue. - - - - - - - a #GQueue. - - - - the data for the new element. - - - - - - Adds a new element at the head of the queue. - - - - - - - a #GQueue - - - - a single #GList element, not a list with more than one element - - - - - - - - Inserts a new element into @queue at the given position. - - - - - - - a #GQueue - - - - the data for the new element - - - - the position to insert the new element. If @n is negative or - larger than the number of elements in the @queue, the element is - added to the end of the queue. - - - - - - Inserts @link into @queue at the given position. - - - - - - - a #GQueue - - - - the position to insert the link. If this is negative or larger than - the number of elements in @queue, the link is added to the end of - @queue. - - - - the link to add to @queue - - - - - - - - Adds a new element at the tail of the queue. - - - - - - - a #GQueue - - - - the data for the new element - - - - - - Adds a new element at the tail of the queue. - - - - - - - a #GQueue - - - - a single #GList element, not a list with more than one element - - - - - - - - Removes the first element in @queue that contains @data. - - - %TRUE if @data was found and removed from @queue - - - - - a #GQueue - - - - the data to remove - - - - - - Remove all elements whose data equals @data from @queue. - - - the number of elements removed from @queue - - - - - a #GQueue - - - - the data to remove - - - - - - Reverses the order of the items in @queue. - - - - - - - a #GQueue - - - - - - Sorts @queue using @compare_func. - - - - - - - a #GQueue - - - - the #GCompareDataFunc used to sort @queue. This function - is passed two elements of the queue and should return 0 if they are - equal, a negative value if the first comes before the second, and - a positive value if the second comes before the first. - - - - user data passed to @compare_func - - - - - - Unlinks @link_ so that it will no longer be part of @queue. -The link is not freed. - -@link_ must be part of @queue. - - - - - - - a #GQueue - - - - a #GList link that must be part of @queue - - - - - - - - Creates a new #GQueue. - - - a newly allocated #GQueue - - - - - - The GRWLock struct is an opaque data structure to represent a -reader-writer lock. It is similar to a #GMutex in that it allows -multiple threads to coordinate access to a shared resource. - -The difference to a mutex is that a reader-writer lock discriminates -between read-only ('reader') and full ('writer') access. While only -one thread at a time is allowed write access (by holding the 'writer' -lock via g_rw_lock_writer_lock()), multiple threads can gain -simultaneous read-only access (by holding the 'reader' lock via -g_rw_lock_reader_lock()). - -It is unspecified whether readers or writers have priority in acquiring the -lock when a reader already holds the lock and a writer is queued to acquire -it. - -Here is an example for an array with access functions: -|[<!-- language="C" --> - GRWLock lock; - GPtrArray *array; - - gpointer - my_array_get (guint index) - { - gpointer retval = NULL; - - if (!array) - return NULL; - - g_rw_lock_reader_lock (&lock); - if (index < array->len) - retval = g_ptr_array_index (array, index); - g_rw_lock_reader_unlock (&lock); - - return retval; - } - - void - my_array_set (guint index, gpointer data) - { - g_rw_lock_writer_lock (&lock); - - if (!array) - array = g_ptr_array_new (); - - if (index >= array->len) - g_ptr_array_set_size (array, index+1); - g_ptr_array_index (array, index) = data; - - g_rw_lock_writer_unlock (&lock); - } - ]| -This example shows an array which can be accessed by many readers -(the my_array_get() function) simultaneously, whereas the writers -(the my_array_set() function) will only be allowed one at a time -and only if no readers currently access the array. This is because -of the potentially dangerous resizing of the array. Using these -functions is fully multi-thread safe now. - -If a #GRWLock is allocated in static storage then it can be used -without initialisation. Otherwise, you should call -g_rw_lock_init() on it and g_rw_lock_clear() when done. - -A GRWLock should only be accessed with the g_rw_lock_ functions. - - - - - - - - - - - Frees the resources allocated to a lock with g_rw_lock_init(). - -This function should not be used with a #GRWLock that has been -statically allocated. - -Calling g_rw_lock_clear() when any thread holds the lock -leads to undefined behaviour. - -Sine: 2.32 - - - - - - - an initialized #GRWLock - - - - - - Initializes a #GRWLock so that it can be used. - -This function is useful to initialize a lock that has been -allocated on the stack, or as part of a larger structure. It is not -necessary to initialise a reader-writer lock that has been statically -allocated. - -|[<!-- language="C" --> - typedef struct { - GRWLock l; - ... - } Blob; - -Blob *b; - -b = g_new (Blob, 1); -g_rw_lock_init (&b->l); -]| - -To undo the effect of g_rw_lock_init() when a lock is no longer -needed, use g_rw_lock_clear(). - -Calling g_rw_lock_init() on an already initialized #GRWLock leads -to undefined behaviour. - - - - - - - an uninitialized #GRWLock - - - - - - Obtain a read lock on @rw_lock. If another thread currently holds -the write lock on @rw_lock, the current thread will block. If another thread -does not hold the write lock, but is waiting for it, it is implementation -defined whether the reader or writer will block. Read locks can be taken -recursively. - -It is implementation-defined how many threads are allowed to -hold read locks on the same lock simultaneously. If the limit is hit, -or if a deadlock is detected, a critical warning will be emitted. - - - - - - - a #GRWLock - - - - - - Tries to obtain a read lock on @rw_lock and returns %TRUE if -the read lock was successfully obtained. Otherwise it -returns %FALSE. - - - %TRUE if @rw_lock could be locked - - - - - a #GRWLock - - - - - - Release a read lock on @rw_lock. - -Calling g_rw_lock_reader_unlock() on a lock that is not held -by the current thread leads to undefined behaviour. - - - - - - - a #GRWLock - - - - - - Obtain a write lock on @rw_lock. If any thread already holds -a read or write lock on @rw_lock, the current thread will block -until all other threads have dropped their locks on @rw_lock. - - - - - - - a #GRWLock - - - - - - Tries to obtain a write lock on @rw_lock. If any other thread holds -a read or write lock on @rw_lock, it immediately returns %FALSE. -Otherwise it locks @rw_lock and returns %TRUE. - - - %TRUE if @rw_lock could be locked - - - - - a #GRWLock - - - - - - Release a write lock on @rw_lock. - -Calling g_rw_lock_writer_unlock() on a lock that is not held -by the current thread leads to undefined behaviour. - - - - - - - a #GRWLock - - - - - - - The GRand struct is an opaque data structure. It should only be -accessed through the g_rand_* functions. - - - Copies a #GRand into a new one with the same exact state as before. -This way you can take a snapshot of the random number generator for -replaying later. - - - the new #GRand - - - - - a #GRand - - - - - - Returns the next random #gdouble from @rand_ equally distributed over -the range [0..1). - - - a random number - - - - - a #GRand - - - - - - Returns the next random #gdouble from @rand_ equally distributed over -the range [@begin..@end). - - - a random number - - - - - a #GRand - - - - lower closed bound of the interval - - - - upper open bound of the interval - - - - - - Frees the memory allocated for the #GRand. - - - - - - - a #GRand - - - - - - Returns the next random #guint32 from @rand_ equally distributed over -the range [0..2^32-1]. - - - a random number - - - - - a #GRand - - - - - - Returns the next random #gint32 from @rand_ equally distributed over -the range [@begin..@end-1]. - - - a random number - - - - - a #GRand - - - - lower closed bound of the interval - - - - upper open bound of the interval - - - - - - Sets the seed for the random number generator #GRand to @seed. - - - - - - - a #GRand - - - - a value to reinitialize the random number generator - - - - - - Initializes the random number generator by an array of longs. -Array can be of arbitrary size, though only the first 624 values -are taken. This function is useful if you have many low entropy -seeds, or if you require more then 32 bits of actual entropy for -your application. - - - - - - - a #GRand - - - - array to initialize with - - - - length of array - - - - - - Creates a new random number generator initialized with a seed taken -either from `/dev/urandom` (if existing) or from the current time -(as a fallback). - -On Windows, the seed is taken from rand_s(). - - - the new #GRand - - - - - Creates a new random number generator initialized with @seed. - - - the new #GRand - - - - - a value to initialize the random number generator - - - - - - Creates a new random number generator initialized with @seed. - - - the new #GRand - - - - - an array of seeds to initialize the random number generator - - - - an array of seeds to initialize the random number - generator - - - - - - - The GRecMutex struct is an opaque data structure to represent a -recursive mutex. It is similar to a #GMutex with the difference -that it is possible to lock a GRecMutex multiple times in the same -thread without deadlock. When doing so, care has to be taken to -unlock the recursive mutex as often as it has been locked. - -If a #GRecMutex is allocated in static storage then it can be used -without initialisation. Otherwise, you should call -g_rec_mutex_init() on it and g_rec_mutex_clear() when done. - -A GRecMutex should only be accessed with the -g_rec_mutex_ functions. - - - - - - - - - - - Frees the resources allocated to a recursive mutex with -g_rec_mutex_init(). - -This function should not be used with a #GRecMutex that has been -statically allocated. - -Calling g_rec_mutex_clear() on a locked recursive mutex leads -to undefined behaviour. - -Sine: 2.32 - - - - - - - an initialized #GRecMutex - - - - - - Initializes a #GRecMutex so that it can be used. - -This function is useful to initialize a recursive mutex -that has been allocated on the stack, or as part of a larger -structure. - -It is not necessary to initialise a recursive mutex that has been -statically allocated. - -|[<!-- language="C" --> - typedef struct { - GRecMutex m; - ... - } Blob; - -Blob *b; - -b = g_new (Blob, 1); -g_rec_mutex_init (&b->m); -]| - -Calling g_rec_mutex_init() on an already initialized #GRecMutex -leads to undefined behaviour. - -To undo the effect of g_rec_mutex_init() when a recursive mutex -is no longer needed, use g_rec_mutex_clear(). - - - - - - - an uninitialized #GRecMutex - - - - - - Locks @rec_mutex. If @rec_mutex is already locked by another -thread, the current thread will block until @rec_mutex is -unlocked by the other thread. If @rec_mutex is already locked -by the current thread, the 'lock count' of @rec_mutex is increased. -The mutex will only become available again when it is unlocked -as many times as it has been locked. - - - - - - - a #GRecMutex - - - - - - Tries to lock @rec_mutex. If @rec_mutex is already locked -by another thread, it immediately returns %FALSE. Otherwise -it locks @rec_mutex and returns %TRUE. - - - %TRUE if @rec_mutex could be locked - - - - - a #GRecMutex - - - - - - Unlocks @rec_mutex. If another thread is blocked in a -g_rec_mutex_lock() call for @rec_mutex, it will become unblocked -and can lock @rec_mutex itself. - -Calling g_rec_mutex_unlock() on a recursive mutex that is not -locked by the current thread leads to undefined behaviour. - - - - - - - a #GRecMutex - - - - - - - The g_regex_*() functions implement regular -expression pattern matching using syntax and semantics similar to -Perl regular expression. - -Some functions accept a @start_position argument, setting it differs -from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL -in the case of a pattern that begins with any kind of lookbehind assertion. -For example, consider the pattern "\Biss\B" which finds occurrences of "iss" -in the middle of words. ("\B" matches only if the current position in the -subject is not a word boundary.) When applied to the string "Mississipi" -from the fourth byte, namely "issipi", it does not match, because "\B" is -always false at the start of the subject, which is deemed to be a word -boundary. However, if the entire string is passed , but with -@start_position set to 4, it finds the second occurrence of "iss" because -it is able to look behind the starting point to discover that it is -preceded by a letter. - -Note that, unless you set the #G_REGEX_RAW flag, all the strings passed -to these functions must be encoded in UTF-8. The lengths and the positions -inside the strings are in bytes and not in characters, so, for instance, -"\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a -single character. If you set #G_REGEX_RAW the strings can be non-valid -UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two -bytes and two characters long. - -When matching a pattern, "\n" matches only against a "\n" character in -the string, and "\r" matches only a "\r" character. To match any newline -sequence use "\R". This particular group matches either the two-character -sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed, -U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), -CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line -separator, U+2028), or PS (paragraph separator, U+2029). - -The behaviour of the dot, circumflex, and dollar metacharacters are -affected by newline characters, the default is to recognize any newline -character (the same characters recognized by "\R"). This can be changed -with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF -compile options, and with #G_REGEX_MATCH_NEWLINE_ANY, -#G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and -#G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also -relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an -unescaped "#" outside a character class is encountered. This indicates -a comment that lasts until after the next newline. - -When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern -matching is changed to be compatible with the way that regular expressions -work in JavaScript. More precisely, a lonely ']' character in the pattern -is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and -you must use the '\u' escape sequence with 4 hex digits to specify a unicode -codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by -the specified number of hex digits, they match 'x' and 'u' literally; also -'\U' always matches 'U' instead of being an error in the pattern. Finally, -pattern matching is modified so that back references to an unset subpattern -group produces a match with the empty string instead of an error. See -pcreapi(3) for more information. - -Creating and manipulating the same #GRegex structure from different -threads is not a problem as #GRegex does not modify its internal -state between creation and destruction, on the other hand #GMatchInfo -is not threadsafe. - -The regular expressions low-level functionalities are obtained through -the excellent -[PCRE](http://www.pcre.org/) -library written by Philip Hazel. - - - Compiles the regular expression to an internal form, and does -the initial setup of the #GRegex structure. - - - a #GRegex structure or %NULL if an error occured. Call - g_regex_unref() when you are done with it - - - - - the regular expression - - - - compile options for the regular expression, or 0 - - - - match options for the regular expression, or 0 - - - - - - Returns the number of capturing subpatterns in the pattern. - - - the number of capturing subpatterns - - - - - a #GRegex - - - - - - Returns the compile options that @regex was created with. - -Depending on the version of PCRE that is used, this may or may not -include flags set by option expressions such as `(?i)` found at the -top-level within the compiled pattern. - - - flags from #GRegexCompileFlags - - - - - a #GRegex - - - - - - Checks whether the pattern contains explicit CR or LF references. - - - %TRUE if the pattern contains explicit CR or LF references - - - - - a #GRegex structure - - - - - - Returns the match options that @regex was created with. - - - flags from #GRegexMatchFlags - - - - - a #GRegex - - - - - - Returns the number of the highest back reference -in the pattern, or 0 if the pattern does not contain -back references. - - - the number of the highest back reference - - - - - a #GRegex - - - - - - Gets the number of characters in the longest lookbehind assertion in the -pattern. This information is useful when doing multi-segment matching using -the partial matching facilities. - - - the number of characters in the longest lookbehind assertion. - - - - - a #GRegex structure - - - - - - Gets the pattern string associated with @regex, i.e. a copy of -the string passed to g_regex_new(). - - - the pattern of @regex - - - - - a #GRegex structure - - - - - - Retrieves the number of the subexpression named @name. - - - The number of the subexpression or -1 if @name - does not exists - - - - - #GRegex structure - - - - name of the subexpression - - - - - - Scans for a match in @string for the pattern in @regex. -The @match_options are combined with the match options specified -when the @regex structure was created, letting you have more -flexibility in reusing #GRegex structures. - -Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - -A #GMatchInfo structure, used to get information on the match, -is stored in @match_info if not %NULL. Note that if @match_info -is not %NULL then it is created even if the function returns %FALSE, -i.e. you must free it regardless if regular expression actually matched. - -To retrieve all the non-overlapping matches of the pattern in -string you can use g_match_info_next(). - -|[<!-- language="C" --> -static void -print_uppercase_words (const gchar *string) -{ - // Print all uppercase-only words. - GRegex *regex; - GMatchInfo *match_info; - - regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - g_regex_match (regex, string, 0, &match_info); - while (g_match_info_matches (match_info)) - { - gchar *word = g_match_info_fetch (match_info, 0); - g_print ("Found: %s\n", word); - g_free (word); - g_match_info_next (match_info, NULL); - } - g_match_info_free (match_info); - g_regex_unref (regex); -} -]| - -@string is not copied and is used in #GMatchInfo internally. If -you use any #GMatchInfo method (except g_match_info_free()) after -freeing or modifying @string then the behaviour is undefined. - - - %TRUE is the string matched, %FALSE otherwise - - - - - a #GRegex structure from g_regex_new() - - - - the string to scan for matches - - - - match options - - - - pointer to location where to store - the #GMatchInfo, or %NULL if you do not need it - - - - - - Using the standard algorithm for regular expression matching only -the longest match in the string is retrieved. This function uses -a different algorithm so it can retrieve all the possible matches. -For more documentation see g_regex_match_all_full(). - -A #GMatchInfo structure, used to get information on the match, is -stored in @match_info if not %NULL. Note that if @match_info is -not %NULL then it is created even if the function returns %FALSE, -i.e. you must free it regardless if regular expression actually -matched. - -@string is not copied and is used in #GMatchInfo internally. If -you use any #GMatchInfo method (except g_match_info_free()) after -freeing or modifying @string then the behaviour is undefined. - - - %TRUE is the string matched, %FALSE otherwise - - - - - a #GRegex structure from g_regex_new() - - - - the string to scan for matches - - - - match options - - - - pointer to location where to store - the #GMatchInfo, or %NULL if you do not need it - - - - - - Using the standard algorithm for regular expression matching only -the longest match in the @string is retrieved, it is not possible -to obtain all the available matches. For instance matching -"<a> <b> <c>" against the pattern "<.*>" -you get "<a> <b> <c>". - -This function uses a different algorithm (called DFA, i.e. deterministic -finite automaton), so it can retrieve all the possible matches, all -starting at the same point in the string. For instance matching -"<a> <b> <c>" against the pattern "<.*>;" -you would obtain three matches: "<a> <b> <c>", -"<a> <b>" and "<a>". - -The number of matched strings is retrieved using -g_match_info_get_match_count(). To obtain the matched strings and -their position you can use, respectively, g_match_info_fetch() and -g_match_info_fetch_pos(). Note that the strings are returned in -reverse order of length; that is, the longest matching string is -given first. - -Note that the DFA algorithm is slower than the standard one and it -is not able to capture substrings, so backreferences do not work. - -Setting @start_position differs from just passing over a shortened -string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern -that begins with any kind of lookbehind assertion, such as "\b". - -Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - -A #GMatchInfo structure, used to get information on the match, is -stored in @match_info if not %NULL. Note that if @match_info is -not %NULL then it is created even if the function returns %FALSE, -i.e. you must free it regardless if regular expression actually -matched. - -@string is not copied and is used in #GMatchInfo internally. If -you use any #GMatchInfo method (except g_match_info_free()) after -freeing or modifying @string then the behaviour is undefined. - - - %TRUE is the string matched, %FALSE otherwise - - - - - a #GRegex structure from g_regex_new() - - - - the string to scan for matches - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - match options - - - - pointer to location where to store - the #GMatchInfo, or %NULL if you do not need it - - - - - - Scans for a match in @string for the pattern in @regex. -The @match_options are combined with the match options specified -when the @regex structure was created, letting you have more -flexibility in reusing #GRegex structures. - -Setting @start_position differs from just passing over a shortened -string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern -that begins with any kind of lookbehind assertion, such as "\b". - -Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - -A #GMatchInfo structure, used to get information on the match, is -stored in @match_info if not %NULL. Note that if @match_info is -not %NULL then it is created even if the function returns %FALSE, -i.e. you must free it regardless if regular expression actually -matched. - -@string is not copied and is used in #GMatchInfo internally. If -you use any #GMatchInfo method (except g_match_info_free()) after -freeing or modifying @string then the behaviour is undefined. - -To retrieve all the non-overlapping matches of the pattern in -string you can use g_match_info_next(). - -|[<!-- language="C" --> -static void -print_uppercase_words (const gchar *string) -{ - // Print all uppercase-only words. - GRegex *regex; - GMatchInfo *match_info; - GError *error = NULL; - - regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); - while (g_match_info_matches (match_info)) - { - gchar *word = g_match_info_fetch (match_info, 0); - g_print ("Found: %s\n", word); - g_free (word); - g_match_info_next (match_info, &error); - } - g_match_info_free (match_info); - g_regex_unref (regex); - if (error != NULL) - { - g_printerr ("Error while matching: %s\n", error->message); - g_error_free (error); - } -} -]| - - - %TRUE is the string matched, %FALSE otherwise - - - - - a #GRegex structure from g_regex_new() - - - - the string to scan for matches - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - match options - - - - pointer to location where to store - the #GMatchInfo, or %NULL if you do not need it - - - - - - Increases reference count of @regex by 1. - - - @regex - - - - - a #GRegex - - - - - - Replaces all occurrences of the pattern in @regex with the -replacement text. Backreferences of the form '\number' or -'\g<number>' in the replacement text are interpolated by the -number-th captured subexpression of the match, '\g<name>' refers -to the captured subexpression with the given name. '\0' refers -to the complete match, but '\0' followed by a number is the octal -representation of a character. To include a literal '\' in the -replacement, write '\\\\'. - -There are also escapes that changes the case of the following text: - -- \l: Convert to lower case the next character -- \u: Convert to upper case the next character -- \L: Convert to lower case till \E -- \U: Convert to upper case till \E -- \E: End case modification - -If you do not need to use backreferences use g_regex_replace_literal(). - -The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was -passed to g_regex_new(). If you want to use not UTF-8 encoded stings -you can use g_regex_replace_literal(). - -Setting @start_position differs from just passing over a shortened -string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that -begins with any kind of lookbehind assertion, such as "\b". - - - a newly allocated string containing the replacements - - - - - a #GRegex structure - - - - the string to perform matches against - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - text to replace each match with - - - - options for the match - - - - - - Replaces occurrences of the pattern in regex with the output of -@eval for that occurrence. - -Setting @start_position differs from just passing over a shortened -string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern -that begins with any kind of lookbehind assertion, such as "\b". - -The following example uses g_regex_replace_eval() to replace multiple -strings at once: -|[<!-- language="C" --> -static gboolean -eval_cb (const GMatchInfo *info, - GString *res, - gpointer data) -{ - gchar *match; - gchar *r; - - match = g_match_info_fetch (info, 0); - r = g_hash_table_lookup ((GHashTable *)data, match); - g_string_append (res, r); - g_free (match); - - return FALSE; -} - -... - -GRegex *reg; -GHashTable *h; -gchar *res; - -h = g_hash_table_new (g_str_hash, g_str_equal); - -g_hash_table_insert (h, "1", "ONE"); -g_hash_table_insert (h, "2", "TWO"); -g_hash_table_insert (h, "3", "THREE"); -g_hash_table_insert (h, "4", "FOUR"); - -reg = g_regex_new ("1|2|3|4", 0, 0, NULL); -res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); -g_hash_table_destroy (h); - -... -]| - - - a newly allocated string containing the replacements - - - - - a #GRegex structure from g_regex_new() - - - - string to perform matches against - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - options for the match - - - - a function to call for each match - - - - user data to pass to the function - - - - - - Replaces all occurrences of the pattern in @regex with the -replacement text. @replacement is replaced literally, to -include backreferences use g_regex_replace(). - -Setting @start_position differs from just passing over a -shortened string and setting #G_REGEX_MATCH_NOTBOL in the -case of a pattern that begins with any kind of lookbehind -assertion, such as "\b". - - - a newly allocated string containing the replacements - - - - - a #GRegex structure - - - - the string to perform matches against - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - text to replace each match with - - - - options for the match - - - - - - Breaks the string on the pattern, and returns an array of the tokens. -If the pattern contains capturing parentheses, then the text for each -of the substrings will also be returned. If the pattern does not match -anywhere in the string, then the whole string is returned as the first -token. - -As a special case, the result of splitting the empty string "" is an -empty vector, not a vector containing a single string. The reason for -this special case is that being able to represent an empty vector is -typically more useful than consistent handling of empty elements. If -you do need to represent empty elements, you'll need to check for the -empty string before calling this function. - -A pattern that can match empty strings splits @string into separate -characters wherever it matches the empty string between characters. -For example splitting "ab c" using as a separator "\s*", you will get -"a", "b" and "c". - - - a %NULL-terminated gchar ** array. Free -it using g_strfreev() - - - - - - - a #GRegex structure - - - - the string to split with the pattern - - - - match time option flags - - - - - - Breaks the string on the pattern, and returns an array of the tokens. -If the pattern contains capturing parentheses, then the text for each -of the substrings will also be returned. If the pattern does not match -anywhere in the string, then the whole string is returned as the first -token. - -As a special case, the result of splitting the empty string "" is an -empty vector, not a vector containing a single string. The reason for -this special case is that being able to represent an empty vector is -typically more useful than consistent handling of empty elements. If -you do need to represent empty elements, you'll need to check for the -empty string before calling this function. - -A pattern that can match empty strings splits @string into separate -characters wherever it matches the empty string between characters. -For example splitting "ab c" using as a separator "\s*", you will get -"a", "b" and "c". - -Setting @start_position differs from just passing over a shortened -string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern -that begins with any kind of lookbehind assertion, such as "\b". - - - a %NULL-terminated gchar ** array. Free -it using g_strfreev() - - - - - - - a #GRegex structure - - - - the string to split with the pattern - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - starting index of the string to match, in bytes - - - - match time option flags - - - - the maximum number of tokens to split @string into. - If this is less than 1, the string is split completely - - - - - - Decreases reference count of @regex by 1. When reference count drops -to zero, it frees all the memory associated with the regex structure. - - - - - - - a #GRegex - - - - - - Checks whether @replacement is a valid replacement string -(see g_regex_replace()), i.e. that all escape sequences in -it are valid. - -If @has_references is not %NULL then @replacement is checked -for pattern references. For instance, replacement text 'foo\n' -does not contain references and may be evaluated without information -about actual match, but '\0\1' (whole match followed by first -subpattern) requires valid #GMatchInfo object. - - - whether @replacement is a valid replacement string - - - - - the replacement string - - - - location to store information about - references in @replacement or %NULL - - - - - - - - - - - Escapes the nul characters in @string to "\x00". It can be used -to compile a regex with embedded nul characters. - -For completeness, @length can be -1 for a nul-terminated string. -In this case the output string will be of course equal to @string. - - - a newly-allocated escaped string - - - - - the string to escape - - - - the length of @string - - - - - - Escapes the special characters used for regular expressions -in @string, for instance "a.b*c" becomes "a\.b\*c". This -function is useful to dynamically generate regular expressions. - -@string can contain nul characters that are replaced with "\0", -in this case remember to specify the correct length of @string -in @length. - - - a newly-allocated escaped string - - - - - the string to escape - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - - - Scans for a match in @string for @pattern. - -This function is equivalent to g_regex_match() but it does not -require to compile the pattern with g_regex_new(), avoiding some -lines of code when you need just to do a match without extracting -substrings, capture counts, and so on. - -If this function is to be called on the same @pattern more than -once, it's more efficient to compile the pattern once with -g_regex_new() and then use g_regex_match(). - - - %TRUE if the string matched, %FALSE otherwise - - - - - the regular expression - - - - the string to scan for matches - - - - compile options for the regular expression, or 0 - - - - match options, or 0 - - - - - - Breaks the string on the pattern, and returns an array of -the tokens. If the pattern contains capturing parentheses, -then the text for each of the substrings will also be returned. -If the pattern does not match anywhere in the string, then the -whole string is returned as the first token. - -This function is equivalent to g_regex_split() but it does -not require to compile the pattern with g_regex_new(), avoiding -some lines of code when you need just to do a split without -extracting substrings, capture counts, and so on. - -If this function is to be called on the same @pattern more than -once, it's more efficient to compile the pattern once with -g_regex_new() and then use g_regex_split(). - -As a special case, the result of splitting the empty string "" -is an empty vector, not a vector containing a single string. -The reason for this special case is that being able to represent -an empty vector is typically more useful than consistent handling -of empty elements. If you do need to represent empty elements, -you'll need to check for the empty string before calling this -function. - -A pattern that can match empty strings splits @string into -separate characters wherever it matches the empty string between -characters. For example splitting "ab c" using as a separator -"\s*", you will get "a", "b" and "c". - - - a %NULL-terminated array of strings. Free -it using g_strfreev() - - - - - - - the regular expression - - - - the string to scan for matches - - - - compile options for the regular expression, or 0 - - - - match options, or 0 - - - - - - - Flags specifying compile-time options. - - - Letters in the pattern match both upper- and - lowercase letters. This option can be changed within a pattern - by a "(?i)" option setting. - - - By default, GRegex treats the strings as consisting - of a single line of characters (even if it actually contains - newlines). The "start of line" metacharacter ("^") matches only - at the start of the string, while the "end of line" metacharacter - ("$") matches only at the end of the string, or before a terminating - newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When - #G_REGEX_MULTILINE is set, the "start of line" and "end of line" - constructs match immediately following or immediately before any - newline in the string, respectively, as well as at the very start - and end. This can be changed within a pattern by a "(?m)" option - setting. - - - A dot metacharacter (".") in the pattern matches all - characters, including newlines. Without it, newlines are excluded. - This option can be changed within a pattern by a ("?s") option setting. - - - Whitespace data characters in the pattern are - totally ignored except when escaped or inside a character class. - Whitespace does not include the VT character (code 11). In addition, - characters between an unescaped "#" outside a character class and - the next newline character, inclusive, are also ignored. This can - be changed within a pattern by a "(?x)" option setting. - - - The pattern is forced to be "anchored", that is, - it is constrained to match only at the first matching point in the - string that is being searched. This effect can also be achieved by - appropriate constructs in the pattern itself such as the "^" - metacharacter. - - - A dollar metacharacter ("$") in the pattern - matches only at the end of the string. Without this option, a - dollar also matches immediately before the final character if - it is a newline (but not before any other newlines). This option - is ignored if #G_REGEX_MULTILINE is set. - - - Inverts the "greediness" of the quantifiers so that - they are not greedy by default, but become greedy if followed by "?". - It can also be set by a "(?U)" option setting within the pattern. - - - Usually strings must be valid UTF-8 strings, using this - flag they are considered as a raw sequence of bytes. - - - Disables the use of numbered capturing - parentheses in the pattern. Any opening parenthesis that is not - followed by "?" behaves as if it were followed by "?:" but named - parentheses can still be used for capturing (and they acquire numbers - in the usual way). - - - Optimize the regular expression. If the pattern will - be used many times, then it may be worth the effort to optimize it - to improve the speed of matches. - - - Limits an unanchored pattern to match before (or at) the - first newline. Since: 2.34 - - - Names used to identify capturing subpatterns need not - be unique. This can be helpful for certain types of pattern when it - is known that only one instance of the named subpattern can ever be - matched. - - - Usually any newline character or character sequence is - recognized. If this option is set, the only recognized newline character - is '\r'. - - - Usually any newline character or character sequence is - recognized. If this option is set, the only recognized newline character - is '\n'. - - - Usually any newline character or character sequence is - recognized. If this option is set, the only recognized newline character - sequence is '\r\n'. - - - Usually any newline character or character sequence - is recognized. If this option is set, the only recognized newline character - sequences are '\r', '\n', and '\r\n'. Since: 2.34 - - - Usually any newline character or character sequence - is recognised. If this option is set, then "\R" only recognizes the newline - characters '\r', '\n' and '\r\n'. Since: 2.34 - - - Changes behaviour so that it is compatible with - JavaScript rather than PCRE. Since: 2.34 - - - - Error codes returned by regular expressions functions. - - - Compilation of the regular expression failed. - - - Optimization of the regular expression failed. - - - Replacement failed due to an ill-formed replacement - string. - - - The match process failed. - - - Internal error of the regular expression engine. - Since 2.16 - - - "\\" at end of pattern. Since 2.16 - - - "\\c" at end of pattern. Since 2.16 - - - Unrecognized character follows "\\". - Since 2.16 - - - Numbers out of order in "{}" - quantifier. Since 2.16 - - - Number too big in "{}" quantifier. - Since 2.16 - - - Missing terminating "]" for - character class. Since 2.16 - - - Invalid escape sequence - in character class. Since 2.16 - - - Range out of order in character class. - Since 2.16 - - - Nothing to repeat. Since 2.16 - - - Unrecognized character after "(?", - "(?<" or "(?P". Since 2.16 - - - POSIX named classes are - supported only within a class. Since 2.16 - - - Missing terminating ")" or ")" - without opening "(". Since 2.16 - - - Reference to non-existent - subpattern. Since 2.16 - - - Missing terminating ")" after comment. - Since 2.16 - - - Regular expression too large. - Since 2.16 - - - Failed to get memory. Since 2.16 - - - Lookbehind assertion is not - fixed length. Since 2.16 - - - Malformed number or name after "(?(". - Since 2.16 - - - Conditional group contains - more than two branches. Since 2.16 - - - Assertion expected after "(?(". - Since 2.16 - - - Unknown POSIX class name. - Since 2.16 - - - POSIX collating - elements are not supported. Since 2.16 - - - Character value in "\\x{...}" sequence - is too large. Since 2.16 - - - Invalid condition "(?(0)". Since 2.16 - - - \\C not allowed in - lookbehind assertion. Since 2.16 - - - Recursive call could loop indefinitely. - Since 2.16 - - - Missing terminator - in subpattern name. Since 2.16 - - - Two named subpatterns have - the same name. Since 2.16 - - - Malformed "\\P" or "\\p" sequence. - Since 2.16 - - - Unknown property name after "\\P" or - "\\p". Since 2.16 - - - Subpattern name is too long - (maximum 32 characters). Since 2.16 - - - Too many named subpatterns (maximum - 10,000). Since 2.16 - - - Octal value is greater than "\\377". - Since 2.16 - - - "DEFINE" group contains more - than one branch. Since 2.16 - - - Repeating a "DEFINE" group is not allowed. - This error is never raised. Since: 2.16 Deprecated: 2.34 - - - Inconsistent newline options. - Since 2.16 - - - "\\g" is not followed by a braced, - angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16 - - - relative reference must not be zero. Since: 2.34 - - - the backtracing - control verb used does not allow an argument. Since: 2.34 - - - unknown backtracing - control verb. Since: 2.34 - - - number is too big in escape sequence. Since: 2.34 - - - Missing subpattern name. Since: 2.34 - - - Missing digit. Since 2.34 - - - In JavaScript compatibility mode, - "[" is an invalid data character. Since: 2.34 - - - different names for subpatterns of the - same number are not allowed. Since: 2.34 - - - the backtracing control - verb requires an argument. Since: 2.34 - - - "\\c" must be followed by an ASCII - character. Since: 2.34 - - - "\\k" is not followed by a braced, angle-bracketed, or - quoted name. Since: 2.34 - - - "\\N" is not supported in a class. Since: 2.34 - - - too many forward references. Since: 2.34 - - - the name is too long in "(*MARK)", "(*PRUNE)", - "(*SKIP)", or "(*THEN)". Since: 2.34 - - - the character value in the \\u sequence is - too large. Since: 2.34 - - - - Specifies the type of the function passed to g_regex_replace_eval(). -It is called for each occurrence of the pattern in the string passed -to g_regex_replace_eval(), and it should append the replacement to -@result. - - - %FALSE to continue the replacement process, %TRUE to stop it - - - - - the #GMatchInfo generated by the match. - Use g_match_info_get_regex() and g_match_info_get_string() if you - need the #GRegex or the matched string. - - - - a #GString containing the new string - - - - user data passed to g_regex_replace_eval() - - - - - - Flags specifying match-time options. - - - The pattern is forced to be "anchored", that is, - it is constrained to match only at the first matching point in the - string that is being searched. This effect can also be achieved by - appropriate constructs in the pattern itself such as the "^" - metacharacter. - - - Specifies that first character of the string is - not the beginning of a line, so the circumflex metacharacter should - not match before it. Setting this without #G_REGEX_MULTILINE (at - compile time) causes circumflex never to match. This option affects - only the behaviour of the circumflex metacharacter, it does not - affect "\A". - - - Specifies that the end of the subject string is - not the end of a line, so the dollar metacharacter should not match - it nor (except in multiline mode) a newline immediately before it. - Setting this without #G_REGEX_MULTILINE (at compile time) causes - dollar never to match. This option affects only the behaviour of - the dollar metacharacter, it does not affect "\Z" or "\z". - - - An empty string is not considered to be a valid - match if this option is set. If there are alternatives in the pattern, - they are tried. If all the alternatives match the empty string, the - entire match fails. For example, if the pattern "a?b?" is applied to - a string not beginning with "a" or "b", it matches the empty string - at the start of the string. With this flag set, this match is not - valid, so GRegex searches further into the string for occurrences - of "a" or "b". - - - Turns on the partial matching feature, for more - documentation on partial matching see g_match_info_is_partial_match(). - - - Overrides the newline definition set when - creating a new #GRegex, setting the '\r' character as line terminator. - - - Overrides the newline definition set when - creating a new #GRegex, setting the '\n' character as line terminator. - - - Overrides the newline definition set when - creating a new #GRegex, setting the '\r\n' characters sequence as line terminator. - - - Overrides the newline definition set when - creating a new #GRegex, any Unicode newline sequence - is recognised as a newline. These are '\r', '\n' and '\rn', and the - single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), - U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and - U+2029 PARAGRAPH SEPARATOR. - - - Overrides the newline definition set when - creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence - is recognized as a newline. Since: 2.34 - - - Overrides the newline definition for "\R" set when - creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences - are recognized as a newline by "\R". Since: 2.34 - - - Overrides the newline definition for "\R" set when - creating a new #GRegex; any Unicode newline character or character sequence - are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the - single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), - U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and - U+2029 PARAGRAPH SEPARATOR. Since: 2.34 - - - An alias for #G_REGEX_MATCH_PARTIAL. Since: 2.34 - - - Turns on the partial matching feature. In contrast to - to #G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match - is found, without continuing to search for a possible complete match. See - g_match_info_is_partial_match() for more information. Since: 2.34 - - - Like #G_REGEX_MATCH_NOTEMPTY, but only applied to - the start of the matched string. For anchored - patterns this can only happen for pattern containing "\K". Since: 2.34 - - - - The search path separator character. -This is ':' on UNIX machines and ';' under Windows. - - - - - The search path separator as a string. -This is ":" on UNIX machines and ";" under Windows. - - - - - - - - - Returns the size of @member in the struct definition without having a -declared instance of @struct_type. - - - - a structure type, e.g. #GOutputVector - - - a field in the structure, e.g. `size` - - - - - - - - - - - - - - - - - The #GSList struct is used for each element in the singly-linked -list. - - - holds the element's data, which can be a pointer to any kind - of data, or any integer value using the - [Type Conversion Macros][glib-Type-Conversion-Macros] - - - - contains the link to the next element in the list. - - - - - - Allocates space for one #GSList element. It is called by the -g_slist_append(), g_slist_prepend(), g_slist_insert() and -g_slist_insert_sorted() functions and so is rarely used on its own. - - - a pointer to the newly-allocated #GSList element. - - - - - - - Adds a new element on to the end of the list. - -The return value is the new start of the list, which may -have changed, so make sure you store the new value. - -Note that g_slist_append() has to traverse the entire list -to find the end, which is inefficient when adding multiple -elements. A common idiom to avoid the inefficiency is to prepend -the elements and reverse the list when all elements have been added. - -|[<!-- language="C" --> -// Notice that these are initialized to the empty list. -GSList *list = NULL, *number_list = NULL; - -// This is a list of strings. -list = g_slist_append (list, "first"); -list = g_slist_append (list, "second"); - -// This is a list of integers. -number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); -number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); -]| - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data for the new element - - - - - - Adds the second #GSList onto the end of the first #GSList. -Note that the elements of the second #GSList are not copied. -They are used directly. - - - the start of the new #GSList - - - - - - - a #GSList - - - - - - the #GSList to add to the end of the first #GSList - - - - - - - - Copies a #GSList. - -Note that this is a "shallow" copy. If the list elements -consist of pointers to data, the pointers are copied but -the actual data isn't. See g_slist_copy_deep() if you need -to copy the data as well. - - - a copy of @list - - - - - - - a #GSList - - - - - - - - Makes a full (deep) copy of a #GSList. - -In contrast with g_slist_copy(), this function uses @func to make a copy of -each list element, in addition to copying the list container itself. - -@func, as a #GCopyFunc, takes two arguments, the data to be copied -and a @user_data pointer. On common processor architectures, it's safe to -pass %NULL as @user_data if the copy function takes only one argument. You -may get compiler warnings from this though if compiling with GCC’s -`-Wcast-function-type` warning. - -For instance, if @list holds a list of GObjects, you can do: -|[<!-- language="C" --> -another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); -]| - -And, to entirely free the new list, you could do: -|[<!-- language="C" --> -g_slist_free_full (another_list, g_object_unref); -]| - - - a full copy of @list, use g_slist_free_full() to free it - - - - - - - a #GSList - - - - - - a copy function used to copy every element in the list - - - - user data passed to the copy function @func, or #NULL - - - - - - Removes the node link_ from the list and frees it. -Compare this to g_slist_remove_link() which removes the node -without freeing it. - -Removing arbitrary nodes from a singly-linked list requires time -that is proportional to the length of the list (ie. O(n)). If you -find yourself using g_slist_delete_link() frequently, you should -consider a different data structure, such as the doubly-linked -#GList. - - - the new head of @list - - - - - - - a #GSList - - - - - - node to delete - - - - - - - - Finds the element in a #GSList which -contains the given data. - - - the found #GSList element, - or %NULL if it is not found - - - - - - - a #GSList - - - - - - the element data to find - - - - - - Finds an element in a #GSList, using a supplied function to -find the desired element. It iterates over the list, calling -the given function which should return 0 when the desired -element is found. The function takes two #gconstpointer arguments, -the #GSList element's data as the first argument and the -given user data. - - - the found #GSList element, or %NULL if it is not found - - - - - - - a #GSList - - - - - - user data passed to the function - - - - the function to call for each element. - It should return 0 when the desired element is found - - - - - - Calls a function for each element of a #GSList. - -It is safe for @func to remove the element from @list, but it must -not modify any part of the list after that element. - - - - - - - a #GSList - - - - - - the function to call with each element's data - - - - user data to pass to the function - - - - - - Frees all of the memory used by a #GSList. -The freed elements are returned to the slice allocator. - -If list elements contain dynamically-allocated memory, -you should either use g_slist_free_full() or free them manually -first. - -It can be combined with g_steal_pointer() to ensure the list head pointer -is not left dangling: -|[<!-- language="C" --> -GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ -g_slist_free (g_steal_pointer (&list_of_borrowed_things)); -]| - - - - - - - a #GSList - - - - - - - - Frees one #GSList element. -It is usually used after g_slist_remove_link(). - - - - - - - a #GSList element - - - - - - - - Convenience method, which frees all the memory used by a #GSList, and -calls the specified destroy function on every element's data. - -@free_func must not modify the list (eg, by removing the freed -element from it). - -It can be combined with g_steal_pointer() to ensure the list head pointer -is not left dangling ­— this also has the nice property that the head pointer -is cleared before any of the list elements are freed, to prevent double frees -from @free_func: -|[<!-- language="C" --> -GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ -g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); -]| - - - - - - - a pointer to a #GSList - - - - - - the function to be called to free each element's data - - - - - - Gets the position of the element containing -the given data (starting from 0). - - - the index of the element containing the data, - or -1 if the data is not found - - - - - a #GSList - - - - - - the data to find - - - - - - Inserts a new element into the list at the given position. - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data for the new element - - - - the position to insert the element. - If this is negative, or is larger than the number - of elements in the list, the new element is added on - to the end of the list. - - - - - - Inserts a node before @sibling containing @data. - - - the new head of the list. - - - - - - - a #GSList - - - - - - node to insert @data before - - - - - - data to put in the newly-inserted node - - - - - - Inserts a new element into the list, using the given -comparison function to determine its position. - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data for the new element - - - - the function to compare elements in the list. - It should return a number > 0 if the first parameter - comes after the second parameter in the sort order. - - - - - - Inserts a new element into the list, using the given -comparison function to determine its position. - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data for the new element - - - - the function to compare elements in the list. - It should return a number > 0 if the first parameter - comes after the second parameter in the sort order. - - - - data to pass to comparison function - - - - - - Gets the last element in a #GSList. - -This function iterates over the whole list. - - - the last element in the #GSList, - or %NULL if the #GSList has no elements - - - - - - - a #GSList - - - - - - - - Gets the number of elements in a #GSList. - -This function iterates over the whole list to -count its elements. To check whether the list is non-empty, it is faster to -check @list against %NULL. - - - the number of elements in the #GSList - - - - - a #GSList - - - - - - - - Gets the element at the given position in a #GSList. - - - the element, or %NULL if the position is off - the end of the #GSList - - - - - - - a #GSList - - - - - - the position of the element, counting from 0 - - - - - - Gets the data of the element at the given position. - - - the element's data, or %NULL if the position - is off the end of the #GSList - - - - - a #GSList - - - - - - the position of the element - - - - - - Gets the position of the given element -in the #GSList (starting from 0). - - - the position of the element in the #GSList, - or -1 if the element is not found - - - - - a #GSList - - - - - - an element in the #GSList - - - - - - - - Adds a new element on to the start of the list. - -The return value is the new start of the list, which -may have changed, so make sure you store the new value. - -|[<!-- language="C" --> -// Notice that it is initialized to the empty list. -GSList *list = NULL; -list = g_slist_prepend (list, "last"); -list = g_slist_prepend (list, "first"); -]| - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data for the new element - - - - - - Removes an element from a #GSList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GSList is unchanged. - - - the new start of the #GSList - - - - - - - a #GSList - - - - - - the data of the element to remove - - - - - - Removes all list nodes with data equal to @data. -Returns the new head of the list. Contrast with -g_slist_remove() which removes only the first node -matching the given data. - - - new head of @list - - - - - - - a #GSList - - - - - - data to remove - - - - - - Removes an element from a #GSList, without -freeing the element. The removed element's next -link is set to %NULL, so that it becomes a -self-contained list with one element. - -Removing arbitrary nodes from a singly-linked list -requires time that is proportional to the length of the list -(ie. O(n)). If you find yourself using g_slist_remove_link() -frequently, you should consider a different data structure, -such as the doubly-linked #GList. - - - the new start of the #GSList, without the element - - - - - - - a #GSList - - - - - - an element in the #GSList - - - - - - - - Reverses a #GSList. - - - the start of the reversed #GSList - - - - - - - a #GSList - - - - - - - - Sorts a #GSList using the given comparison function. The algorithm -used is a stable sort. - - - the start of the sorted #GSList - - - - - - - a #GSList - - - - - - the comparison function used to sort the #GSList. - This function is passed the data from 2 elements of the #GSList - and should return 0 if they are equal, a negative value if the - first element comes before the second, or a positive value if - the first element comes after the second. - - - - - - Like g_slist_sort(), but the sort function accepts a user data argument. - - - new head of the list - - - - - - - a #GSList - - - - - - comparison function - - - - data to pass to comparison function - - - - - - - Use this macro as the return value of a #GSourceFunc to leave -the #GSource in the main loop. - - - - - Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8 -onwards with `-Wextra` or `-Wcast-function-type` enabled about the function -types being incompatible. - -For example, the correct type of callback for a source created by -g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments -than #GSourceFunc. Casting the function with `(GSourceFunc)` to call -g_source_set_callback() will trigger a warning, even though it will be cast -back to the correct type before it is called by the source. - - - - a function pointer. - - - - - Use this macro as the return value of a #GSourceFunc to remove -the #GSource from the main loop. - - - - - The square root of two. - - - - - Accepts a macro or a string and converts it into a string after -preprocessor argument expansion. For example, the following code: - -|[<!-- language="C" --> -#define AGE 27 -const gchar *greeting = G_STRINGIFY (AGE) " today!"; -]| - -is transformed by the preprocessor into (code equivalent to): - -|[<!-- language="C" --> -const gchar *greeting = "27 today!"; -]| - - - - a macro or a string - - - - - - - - - - - - Returns a member of a structure at a given offset, using the given type. - - - - the type of the struct field - - - a pointer to a struct - - - the offset of the field from the start of the struct, - in bytes - - - - - Returns an untyped pointer to a given offset of a struct. - - - - a pointer to a struct - - - the offset from the start of the struct, in bytes - - - - - Returns the offset, in bytes, of a member of a struct. - - - - a structure type, e.g. #GtkWidget - - - a field in the structure, e.g. @window - - - - - The standard delimiters, used in g_strdelimit(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The data structure representing a lexical scanner. - -You should set @input_name after creating the scanner, since -it is used by the default message handler when displaying -warnings and errors. If you are scanning a file, the filename -would be a good choice. - -The @user_data and @max_parse_errors fields are not used. -If you need to associate extra data with the scanner you -can place them here. - -If you want to use your own message handler you can set the -@msg_handler field. The type of the message handler function -is declared by #GScannerMsgFunc. - - - unused - - - - unused - - - - g_scanner_error() increments this field - - - - name of input stream, featured by the default message handler - - - - quarked data - - - - link into the scanner configuration - - - - token parsed by the last g_scanner_get_next_token() - - - - value of the last token from g_scanner_get_next_token() - - - - line number of the last token from g_scanner_get_next_token() - - - - char number of the last token from g_scanner_get_next_token() - - - - token parsed by the last g_scanner_peek_next_token() - - - - value of the last token from g_scanner_peek_next_token() - - - - line number of the last token from g_scanner_peek_next_token() - - - - char number of the last token from g_scanner_peek_next_token() - - - - - - - - - - - - - - - - - - - - - - - - - handler function for _warn and _error - - - - Returns the current line in the input stream (counting -from 1). This is the line of the last token parsed via -g_scanner_get_next_token(). - - - the current line - - - - - a #GScanner - - - - - - Returns the current position in the current line (counting -from 0). This is the position of the last token parsed via -g_scanner_get_next_token(). - - - the current position on the line - - - - - a #GScanner - - - - - - Gets the current token type. This is simply the @token -field in the #GScanner structure. - - - the current token type - - - - - a #GScanner - - - - - - Gets the current token value. This is simply the @value -field in the #GScanner structure. - - - the current token value - - - - - a #GScanner - - - - - - Frees all memory used by the #GScanner. - - - - - - - a #GScanner - - - - - - Returns %TRUE if the scanner has reached the end of -the file or text buffer. - - - %TRUE if the scanner has reached the end of - the file or text buffer - - - - - a #GScanner - - - - - - Outputs an error message, via the #GScanner message handler. - - - - - - - a #GScanner - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Parses the next token just like g_scanner_peek_next_token() -and also removes it from the input stream. The token data is -placed in the @token, @value, @line, and @position fields of -the #GScanner structure. - - - the type of the token - - - - - a #GScanner - - - - - - Prepares to scan a file. - - - - - - - a #GScanner - - - - a file descriptor - - - - - - Prepares to scan a text buffer. - - - - - - - a #GScanner - - - - the text buffer to scan - - - - the length of the text buffer - - - - - - Looks up a symbol in the current scope and return its value. -If the symbol is not bound in the current scope, %NULL is -returned. - - - the value of @symbol in the current scope, or %NULL - if @symbol is not bound in the current scope - - - - - a #GScanner - - - - the symbol to look up - - - - - - Parses the next token, without removing it from the input stream. -The token data is placed in the @next_token, @next_value, @next_line, -and @next_position fields of the #GScanner structure. - -Note that, while the token is not removed from the input stream -(i.e. the next call to g_scanner_get_next_token() will return the -same token), it will not be reevaluated. This can lead to surprising -results when changing scope or the scanner configuration after peeking -the next token. Getting the next token after switching the scope or -configuration will return whatever was peeked before, regardless of -any symbols that may have been added or removed in the new scope. - - - the type of the token - - - - - a #GScanner - - - - - - Adds a symbol to the given scope. - - - - - - - a #GScanner - - - - the scope id - - - - the symbol to add - - - - the value of the symbol - - - - - - Calls the given function for each of the symbol/value pairs -in the given scope of the #GScanner. The function is passed -the symbol and value of each pair, and the given @user_data -parameter. - - - - - - - a #GScanner - - - - the scope id - - - - the function to call for each symbol/value pair - - - - user data to pass to the function - - - - - - Looks up a symbol in a scope and return its value. If the -symbol is not bound in the scope, %NULL is returned. - - - the value of @symbol in the given scope, or %NULL - if @symbol is not bound in the given scope. - - - - - a #GScanner - - - - the scope id - - - - the symbol to look up - - - - - - Removes a symbol from a scope. - - - - - - - a #GScanner - - - - the scope id - - - - the symbol to remove - - - - - - Sets the current scope. - - - the old scope id - - - - - a #GScanner - - - - the new scope id - - - - - - Rewinds the filedescriptor to the current buffer position -and blows the file read ahead buffer. This is useful for -third party uses of the scanners filedescriptor, which hooks -onto the current scanning position. - - - - - - - a #GScanner - - - - - - Outputs a message through the scanner's msg_handler, -resulting from an unexpected token in the input stream. -Note that you should not call g_scanner_peek_next_token() -followed by g_scanner_unexp_token() without an intermediate -call to g_scanner_get_next_token(), as g_scanner_unexp_token() -evaluates the scanner's current token (not the peeked token) -to construct part of the message. - - - - - - - a #GScanner - - - - the expected token - - - - a string describing how the scanner's user - refers to identifiers (%NULL defaults to "identifier"). - This is used if @expected_token is %G_TOKEN_IDENTIFIER or - %G_TOKEN_IDENTIFIER_NULL. - - - - a string describing how the scanner's user refers - to symbols (%NULL defaults to "symbol"). This is used if - @expected_token is %G_TOKEN_SYMBOL or any token value greater - than %G_TOKEN_LAST. - - - - the name of the symbol, if the scanner's current - token is a symbol. - - - - a message string to output at the end of the - warning/error, or %NULL. - - - - if %TRUE it is output as an error. If %FALSE it is - output as a warning. - - - - - - Outputs a warning message, via the #GScanner message handler. - - - - - - - a #GScanner - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Creates a new #GScanner. - -The @config_templ structure specifies the initial settings -of the scanner, which are copied into the #GScanner -@config field. If you pass %NULL then the default settings -are used. - - - the new #GScanner - - - - - the initial scanner settings - - - - - - - Specifies the #GScanner parser configuration. Most settings can -be changed during the parsing phase and will affect the lexical -parsing of the next unpeeked token. - - - specifies which characters should be skipped - by the scanner (the default is the whitespace characters: space, - tab, carriage-return and line-feed). - - - - specifies the characters which can start - identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). - - - - specifies the characters which can be used - in identifiers, after the first character (the default is - #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, - #G_CSET_LATINC). - - - - specifies the characters at the start and - end of single-line comments. The default is "#\n" which means - that single-line comments start with a '#' and continue until - a '\n' (end of line). - - - - specifies if symbols are case sensitive (the - default is %FALSE). - - - - specifies if multi-line comments are skipped - and not returned as tokens (the default is %TRUE). - - - - specifies if single-line comments are skipped - and not returned as tokens (the default is %TRUE). - - - - specifies if multi-line comments are recognized - (the default is %TRUE). - - - - specifies if identifiers are recognized (the - default is %TRUE). - - - - specifies if single-character - identifiers are recognized (the default is %FALSE). - - - - specifies if %NULL is reported as - %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). - - - - specifies if symbols are recognized (the default - is %TRUE). - - - - specifies if binary numbers are recognized (the - default is %FALSE). - - - - specifies if octal numbers are recognized (the - default is %TRUE). - - - - specifies if floating point numbers are recognized - (the default is %TRUE). - - - - specifies if hexadecimal numbers are recognized (the - default is %TRUE). - - - - specifies if '$' is recognized as a prefix for - hexadecimal numbers (the default is %FALSE). - - - - specifies if strings can be enclosed in single - quotes (the default is %TRUE). - - - - specifies if strings can be enclosed in double - quotes (the default is %TRUE). - - - - specifies if binary, octal and hexadecimal numbers - are reported as #G_TOKEN_INT (the default is %TRUE). - - - - specifies if all numbers are reported as %G_TOKEN_FLOAT - (the default is %FALSE). - - - - specifies if identifiers are reported as strings - (the default is %FALSE). - - - - specifies if characters are reported by setting - `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). - - - - specifies if symbols are reported by setting - `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). - - - - specifies if a symbol is searched for in the - default scope in addition to the current scope (the default is %FALSE). - - - - use value.v_int64 rather than v_int - - - - - - - - Specifies the type of the message handler function. - - - - - - - a #GScanner - - - - the message - - - - %TRUE if the message signals an error, - %FALSE if it signals a warning. - - - - - - An enumeration specifying the base position for a -g_io_channel_seek_position() operation. - - - the current position in the file. - - - the start of the file. - - - the end of the file. - - - - The #GSequence struct is an opaque data type representing a -[sequence][glib-Sequences] data type. - - - Adds a new item to the end of @seq. - - - an iterator pointing to the new item - - - - - a #GSequence - - - - the data for the new item - - - - - - Calls @func for each item in the sequence passing @user_data -to the function. @func must not modify the sequence itself. - - - - - - - a #GSequence - - - - the function to call for each item in @seq - - - - user data passed to @func - - - - - - Frees the memory allocated for @seq. If @seq has a data destroy -function associated with it, that function is called on all items -in @seq. - - - - - - - a #GSequence - - - - - - Returns the begin iterator for @seq. - - - the begin iterator for @seq. - - - - - a #GSequence - - - - - - Returns the end iterator for @seg - - - the end iterator for @seq - - - - - a #GSequence - - - - - - Returns the iterator at position @pos. If @pos is negative or larger -than the number of items in @seq, the end iterator is returned. - - - The #GSequenceIter at position @pos - - - - - a #GSequence - - - - a position in @seq, or -1 for the end - - - - - - Returns the length of @seq. Note that this method is O(h) where `h' is the -height of the tree. It is thus more efficient to use g_sequence_is_empty() -when comparing the length to zero. - - - the length of @seq - - - - - a #GSequence - - - - - - Inserts @data into @seq using @cmp_func to determine the new -position. The sequence must already be sorted according to @cmp_func; -otherwise the new position of @data is undefined. - -@cmp_func is called with two items of the @seq, and @cmp_data. -It should return 0 if the items are equal, a negative value -if the first item comes before the second, and a positive value -if the second item comes before the first. - -Note that when adding a large amount of data to a #GSequence, -it is more efficient to do unsorted insertions and then call -g_sequence_sort() or g_sequence_sort_iter(). - - - a #GSequenceIter pointing to the new item. - - - - - a #GSequence - - - - the data to insert - - - - the function used to compare items in the sequence - - - - user data passed to @cmp_func. - - - - - - Like g_sequence_insert_sorted(), but uses -a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as -the compare function. - -@iter_cmp is called with two iterators pointing into @seq. -It should return 0 if the iterators are equal, a negative -value if the first iterator comes before the second, and a -positive value if the second iterator comes before the first. - -Note that when adding a large amount of data to a #GSequence, -it is more efficient to do unsorted insertions and then call -g_sequence_sort() or g_sequence_sort_iter(). - - - a #GSequenceIter pointing to the new item - - - - - a #GSequence - - - - data for the new item - - - - the function used to compare iterators in the sequence - - - - user data passed to @iter_cmp - - - - - - Returns %TRUE if the sequence contains zero items. - -This function is functionally identical to checking the result of -g_sequence_get_length() being equal to zero. However this function is -implemented in O(1) running time. - - - %TRUE if the sequence is empty, otherwise %FALSE. - - - - - a #GSequence - - - - - - Returns an iterator pointing to the position of the first item found -equal to @data according to @cmp_func and @cmp_data. If more than one -item is equal, it is not guaranteed that it is the first which is -returned. In that case, you can use g_sequence_iter_next() and -g_sequence_iter_prev() to get others. - -@cmp_func is called with two items of the @seq, and @cmp_data. -It should return 0 if the items are equal, a negative value if -the first item comes before the second, and a positive value if -the second item comes before the first. - -This function will fail if the data contained in the sequence is -unsorted. - - - an #GSequenceIter pointing to the position of the - first item found equal to @data according to @cmp_func and - @cmp_data, or %NULL if no such item exists - - - - - a #GSequence - - - - data to look up - - - - the function used to compare items in the sequence - - - - user data passed to @cmp_func - - - - - - Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc -instead of a #GCompareDataFunc as the compare function. - -@iter_cmp is called with two iterators pointing into @seq. -It should return 0 if the iterators are equal, a negative value -if the first iterator comes before the second, and a positive -value if the second iterator comes before the first. - -This function will fail if the data contained in the sequence is -unsorted. - - - an #GSequenceIter pointing to the position of - the first item found equal to @data according to @iter_cmp - and @cmp_data, or %NULL if no such item exists - - - - - a #GSequence - - - - data to look up - - - - the function used to compare iterators in the sequence - - - - user data passed to @iter_cmp - - - - - - Adds a new item to the front of @seq - - - an iterator pointing to the new item - - - - - a #GSequence - - - - the data for the new item - - - - - - Returns an iterator pointing to the position where @data would -be inserted according to @cmp_func and @cmp_data. - -@cmp_func is called with two items of the @seq, and @cmp_data. -It should return 0 if the items are equal, a negative value if -the first item comes before the second, and a positive value if -the second item comes before the first. - -If you are simply searching for an existing element of the sequence, -consider using g_sequence_lookup(). - -This function will fail if the data contained in the sequence is -unsorted. - - - an #GSequenceIter pointing to the position where @data - would have been inserted according to @cmp_func and @cmp_data - - - - - a #GSequence - - - - data for the new item - - - - the function used to compare items in the sequence - - - - user data passed to @cmp_func - - - - - - Like g_sequence_search(), but uses a #GSequenceIterCompareFunc -instead of a #GCompareDataFunc as the compare function. - -@iter_cmp is called with two iterators pointing into @seq. -It should return 0 if the iterators are equal, a negative value -if the first iterator comes before the second, and a positive -value if the second iterator comes before the first. - -If you are simply searching for an existing element of the sequence, -consider using g_sequence_lookup_iter(). - -This function will fail if the data contained in the sequence is -unsorted. - - - a #GSequenceIter pointing to the position in @seq - where @data would have been inserted according to @iter_cmp - and @cmp_data - - - - - a #GSequence - - - - data for the new item - - - - the function used to compare iterators in the sequence - - - - user data passed to @iter_cmp - - - - - - Sorts @seq using @cmp_func. - -@cmp_func is passed two items of @seq and should -return 0 if they are equal, a negative value if the -first comes before the second, and a positive value -if the second comes before the first. - - - - - - - a #GSequence - - - - the function used to sort the sequence - - - - user data passed to @cmp_func - - - - - - Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead -of a #GCompareDataFunc as the compare function - -@cmp_func is called with two iterators pointing into @seq. It should -return 0 if the iterators are equal, a negative value if the first -iterator comes before the second, and a positive value if the second -iterator comes before the first. - - - - - - - a #GSequence - - - - the function used to compare iterators in the sequence - - - - user data passed to @cmp_func - - - - - - Calls @func for each item in the range (@begin, @end) passing -@user_data to the function. @func must not modify the sequence -itself. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - a #GFunc - - - - user data passed to @func - - - - - - Returns the data that @iter points to. - - - the data that @iter points to - - - - - a #GSequenceIter - - - - - - Inserts a new item just before the item pointed to by @iter. - - - an iterator pointing to the new item - - - - - a #GSequenceIter - - - - the data for the new item - - - - - - Moves the item pointed to by @src to the position indicated by @dest. -After calling this function @dest will point to the position immediately -after @src. It is allowed for @src and @dest to point into different -sequences. - - - - - - - a #GSequenceIter pointing to the item to move - - - - a #GSequenceIter pointing to the position to which - the item is moved - - - - - - Inserts the (@begin, @end) range at the destination pointed to by @dest. -The @begin and @end iters must point into the same sequence. It is -allowed for @dest to point to a different sequence than the one pointed -into by @begin and @end. - -If @dest is %NULL, the range indicated by @begin and @end is -removed from the sequence. If @dest points to a place within -the (@begin, @end) range, the range does not move. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Creates a new GSequence. The @data_destroy function, if non-%NULL will -be called on all items when the sequence is destroyed and on items that -are removed from the sequence. - - - a new #GSequence - - - - - a #GDestroyNotify function, or %NULL - - - - - - Finds an iterator somewhere in the range (@begin, @end). This -iterator will be close to the middle of the range, but is not -guaranteed to be exactly in the middle. - -The @begin and @end iterators must both point to the same sequence -and @begin must come before or be equal to @end in the sequence. - - - a #GSequenceIter pointing somewhere in the - (@begin, @end) range - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Removes the item pointed to by @iter. It is an error to pass the -end iterator to this function. - -If the sequence has a data destroy function associated with it, this -function is called on the data for the removed item. - - - - - - - a #GSequenceIter - - - - - - Removes all items in the (@begin, @end) range. - -If the sequence has a data destroy function associated with it, this -function is called on the data for the removed items. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Changes the data for the item pointed to by @iter to be @data. If -the sequence has a data destroy function associated with it, that -function is called on the existing data that @iter pointed to. - - - - - - - a #GSequenceIter - - - - new data for the item - - - - - - Moves the data pointed to by @iter to a new position as indicated by -@cmp_func. This -function should be called for items in a sequence already sorted according -to @cmp_func whenever some aspect of an item changes so that @cmp_func -may return different values for that item. - -@cmp_func is called with two items of the @seq, and @cmp_data. -It should return 0 if the items are equal, a negative value if -the first item comes before the second, and a positive value if -the second item comes before the first. - - - - - - - A #GSequenceIter - - - - the function used to compare items in the sequence - - - - user data passed to @cmp_func. - - - - - - Like g_sequence_sort_changed(), but uses -a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as -the compare function. - -@iter_cmp is called with two iterators pointing into the #GSequence that -@iter points into. It should -return 0 if the iterators are equal, a negative value if the first -iterator comes before the second, and a positive value if the second -iterator comes before the first. - - - - - - - a #GSequenceIter - - - - the function used to compare iterators in the sequence - - - - user data passed to @cmp_func - - - - - - Swaps the items pointed to by @a and @b. It is allowed for @a and @b -to point into difference sequences. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - - The #GSequenceIter struct is an opaque data type representing an -iterator pointing into a #GSequence. - - - Returns a negative number if @a comes before @b, 0 if they are equal, -and a positive number if @a comes after @b. - -The @a and @b iterators must point into the same sequence. - - - a negative number if @a comes before @b, 0 if they are - equal, and a positive number if @a comes after @b - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Returns the position of @iter - - - the position of @iter - - - - - a #GSequenceIter - - - - - - Returns the #GSequence that @iter points into. - - - the #GSequence that @iter points into - - - - - a #GSequenceIter - - - - - - Returns whether @iter is the begin iterator - - - whether @iter is the begin iterator - - - - - a #GSequenceIter - - - - - - Returns whether @iter is the end iterator - - - Whether @iter is the end iterator - - - - - a #GSequenceIter - - - - - - Returns the #GSequenceIter which is @delta positions away from @iter. -If @iter is closer than -@delta positions to the beginning of the sequence, -the begin iterator is returned. If @iter is closer than @delta positions -to the end of the sequence, the end iterator is returned. - - - a #GSequenceIter which is @delta positions away from @iter - - - - - a #GSequenceIter - - - - A positive or negative number indicating how many positions away - from @iter the returned #GSequenceIter will be - - - - - - Returns an iterator pointing to the next position after @iter. -If @iter is the end iterator, the end iterator is returned. - - - a #GSequenceIter pointing to the next position after @iter - - - - - a #GSequenceIter - - - - - - Returns an iterator pointing to the previous position before @iter. -If @iter is the begin iterator, the begin iterator is returned. - - - a #GSequenceIter pointing to the previous position - before @iter - - - - - a #GSequenceIter - - - - - - - A #GSequenceIterCompareFunc is a function used to compare iterators. -It must return zero if the iterators compare equal, a negative value -if @a comes before @b, and a positive value if @b comes before @a. - - - zero if the iterators are equal, a negative value if @a - comes before @b, and a positive value if @b comes before @a. - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - user data - - - - - - Error codes returned by shell functions. - - - Mismatched or otherwise mangled quoting. - - - String to be parsed was empty. - - - Some other error. - - - - - - - - - - - - - - - - - - - The `GSource` struct is an opaque data type -representing an event source. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a new #GSource structure. The size is specified to -allow creating structures derived from #GSource that contain -additional data. The size passed in must be at least -`sizeof (GSource)`. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. - - - the newly-created #GSource. - - - - - structure containing functions that implement - the sources behavior. - - - - size of the #GSource structure to create. - - - - - - Adds @child_source to @source as a "polled" source; when @source is -added to a #GMainContext, @child_source will be automatically added -with the same priority, when @child_source is triggered, it will -cause @source to dispatch (in addition to calling its own -callback), and when @source is destroyed, it will destroy -@child_source as well. (@source will also still be dispatched if -its own prepare/check functions indicate that it is ready.) - -If you don't need @child_source to do anything on its own when it -triggers, you can call g_source_set_dummy_callback() on it to set a -callback that does nothing (except return %TRUE if appropriate). - -@source will hold a reference on @child_source while @child_source -is attached to it. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - - - - - - - a #GSource - - - - a second #GSource that @source should "poll" - - - - - - Adds a file descriptor to the set of file descriptors polled for -this source. This is usually combined with g_source_new() to add an -event source. The event source's check function will typically test -the @revents field in the #GPollFD struct and return %TRUE if events need -to be processed. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - -Using this API forces the linear scanning of event sources on each -main loop iteration. Newly-written event sources should try to use -g_source_add_unix_fd() instead of this API. - - - - - - - a #GSource - - - - a #GPollFD structure holding information about a file - descriptor to watch. - - - - - - Monitors @fd for the IO events in @events. - -The tag returned by this function can be used to remove or modify the -monitoring of the fd using g_source_remove_unix_fd() or -g_source_modify_unix_fd(). - -It is not necessary to remove the fd before destroying the source; it -will be cleaned up automatically. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - -As the name suggests, this function is not available on Windows. - - - an opaque tag - - - - - a #GSource - - - - the fd to monitor - - - - an event mask - - - - - - Adds a #GSource to a @context so that it will be executed within -that context. Remove it by calling g_source_destroy(). - -This function is safe to call from any thread, regardless of which thread -the @context is running in. - - - the ID (greater than 0) for the source within the - #GMainContext. - - - - - a #GSource - - - - a #GMainContext (if %NULL, the default context will be used) - - - - - - Removes a source from its #GMainContext, if any, and mark it as -destroyed. The source cannot be subsequently added to another -context. It is safe to call this on sources which have already been -removed from their context. - -This does not unref the #GSource: if you still hold a reference, use -g_source_unref() to drop it. - -This function is safe to call from any thread, regardless of which thread -the #GMainContext is running in. - - - - - - - a #GSource - - - - - - Checks whether a source is allowed to be called recursively. -see g_source_set_can_recurse(). - - - whether recursion is allowed. - - - - - a #GSource - - - - - - Gets the #GMainContext with which the source is associated. - -You can call this on a source that has been destroyed, provided -that the #GMainContext it was attached to still exists (in which -case it will return that #GMainContext). In particular, you can -always call this function on the source returned from -g_main_current_source(). But calling this function on a source -whose #GMainContext has been destroyed is an error. - - - the #GMainContext with which the - source is associated, or %NULL if the context has not - yet been added to a source. - - - - - a #GSource - - - - - - This function ignores @source and is otherwise the same as -g_get_current_time(). - use g_source_get_time() instead - - - - - - - a #GSource - - - - #GTimeVal structure in which to store current time. - - - - - - Returns the numeric ID for a particular source. The ID of a source -is a positive integer which is unique within a particular main loop -context. The reverse -mapping from ID to source is done by g_main_context_find_source_by_id(). - -You can only call this function while the source is associated to a -#GMainContext instance; calling this function before g_source_attach() -or after g_source_destroy() yields undefined behavior. The ID returned -is unique within the #GMainContext instance passed to g_source_attach(). - - - the ID (greater than 0) for the source - - - - - a #GSource - - - - - - Gets a name for the source, used in debugging and profiling. The -name may be #NULL if it has never been set with g_source_set_name(). - - - the name of the source - - - - - a #GSource - - - - - - Gets the priority of a source. - - - the priority of the source - - - - - a #GSource - - - - - - Gets the "ready time" of @source, as set by -g_source_set_ready_time(). - -Any time before the current monotonic time (including 0) is an -indication that the source will fire immediately. - - - the monotonic ready time, -1 for "never" - - - - - a #GSource - - - - - - Gets the time to be used when checking this source. The advantage of -calling this function over calling g_get_monotonic_time() directly is -that when checking multiple sources, GLib can cache a single value -instead of having to repeatedly get the system monotonic time. - -The time here is the system monotonic time, if available, or some -other reasonable alternative otherwise. See g_get_monotonic_time(). - - - the monotonic time in microseconds - - - - - a #GSource - - - - - - Returns whether @source has been destroyed. - -This is important when you operate upon your objects -from within idle handlers, but may have freed the object -before the dispatch of your idle handler. - -|[<!-- language="C" --> -static gboolean -idle_callback (gpointer data) -{ - SomeWidget *self = data; - - GDK_THREADS_ENTER (); - // do stuff with self - self->idle_id = 0; - GDK_THREADS_LEAVE (); - - return G_SOURCE_REMOVE; -} - -static void -some_widget_do_stuff_later (SomeWidget *self) -{ - self->idle_id = g_idle_add (idle_callback, self); -} - -static void -some_widget_finalize (GObject *object) -{ - SomeWidget *self = SOME_WIDGET (object); - - if (self->idle_id) - g_source_remove (self->idle_id); - - G_OBJECT_CLASS (parent_class)->finalize (object); -} -]| - -This will fail in a multi-threaded application if the -widget is destroyed before the idle handler fires due -to the use after free in the callback. A solution, to -this particular problem, is to check to if the source -has already been destroy within the callback. - -|[<!-- language="C" --> -static gboolean -idle_callback (gpointer data) -{ - SomeWidget *self = data; - - GDK_THREADS_ENTER (); - if (!g_source_is_destroyed (g_main_current_source ())) - { - // do stuff with self - } - GDK_THREADS_LEAVE (); - - return FALSE; -} -]| - -Calls to this function from a thread other than the one acquired by the -#GMainContext the #GSource is attached to are typically redundant, as the -source could be destroyed immediately after this function returns. However, -once a source is destroyed it cannot be un-destroyed, so this function can be -used for opportunistic checks from any thread. - - - %TRUE if the source has been destroyed - - - - - a #GSource - - - - - - Updates the event mask to watch for the fd identified by @tag. - -@tag is the tag returned from g_source_add_unix_fd(). - -If you want to remove a fd, don't set its event mask to zero. -Instead, call g_source_remove_unix_fd(). - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - -As the name suggests, this function is not available on Windows. - - - - - - - a #GSource - - - - the tag from g_source_add_unix_fd() - - - - the new event mask to watch - - - - - - Queries the events reported for the fd corresponding to @tag on -@source during the last poll. - -The return value of this function is only defined when the function -is called from the check or dispatch functions for @source. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - -As the name suggests, this function is not available on Windows. - - - the conditions reported on the fd - - - - - a #GSource - - - - the tag from g_source_add_unix_fd() - - - - - - Increases the reference count on a source by one. - - - @source - - - - - a #GSource - - - - - - Detaches @child_source from @source and destroys it. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - - - - - - - a #GSource - - - - a #GSource previously passed to - g_source_add_child_source(). - - - - - - Removes a file descriptor from the set of file descriptors polled for -this source. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - - - - - - - a #GSource - - - - a #GPollFD structure previously passed to g_source_add_poll(). - - - - - - Reverses the effect of a previous call to g_source_add_unix_fd(). - -You only need to call this if you want to remove an fd from being -watched while keeping the same source around. In the normal case you -will just want to destroy the source. - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - -As the name suggests, this function is not available on Windows. - - - - - - - a #GSource - - - - the tag from g_source_add_unix_fd() - - - - - - Sets the callback function for a source. The callback for a source is -called from the source's dispatch function. - -The exact type of @func depends on the type of source; ie. you -should not count on @func being called with @data as its first -parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about -incompatible function types. - -See [memory management of sources][mainloop-memory-management] for details -on how to handle memory management of @data. - -Typically, you won't use this function. Instead use functions specific -to the type of source you are using, such as g_idle_add() or g_timeout_add(). - -It is safe to call this function multiple times on a source which has already -been attached to a context. The changes will take effect for the next time -the source is dispatched after this call returns. - - - - - - - the source - - - - a callback function - - - - the data to pass to callback function - - - - a function to call when @data is no longer in use, or %NULL. - - - - - - Sets the callback function storing the data as a refcounted callback -"object". This is used internally. Note that calling -g_source_set_callback_indirect() assumes -an initial reference count on @callback_data, and thus -@callback_funcs->unref will eventually be called once more -than @callback_funcs->ref. - -It is safe to call this function multiple times on a source which has already -been attached to a context. The changes will take effect for the next time -the source is dispatched after this call returns. - - - - - - - the source - - - - pointer to callback data "object" - - - - functions for reference counting @callback_data - and getting the callback and data - - - - - - Sets whether a source can be called recursively. If @can_recurse is -%TRUE, then while the source is being dispatched then this source -will be processed normally. Otherwise, all processing of this -source is blocked until the dispatch function returns. - - - - - - - a #GSource - - - - whether recursion is allowed for this source - - - - - - Set @dispose as dispose function on @source. @dispose will be called once -the reference count of @source reaches 0 but before any of the state of the -source is freed, especially before the finalize function is called. - -This means that at this point @source is still a valid #GSource and it is -allow for the reference count to increase again until @dispose returns. - -The dispose function can be used to clear any "weak" references to the -@source in other data structures in a thread-safe way where it is possible -for another thread to increase the reference count of @source again while -it is being freed. - -The finalize function can not be used for this purpose as at that point -@source is already partially freed and not valid anymore. - -This should only ever be called from #GSource implementations. - - - - - - - A #GSource to set the dispose function on - - - - #GSourceDisposeFunc to set on the source - - - - - - Sets the source functions (can be used to override -default implementations) of an unattached source. - - - - - - - a #GSource - - - - the new #GSourceFuncs - - - - - - Sets a name for the source, used in debugging and profiling. -The name defaults to #NULL. - -The source name should describe in a human-readable way -what the source does. For example, "X11 event queue" -or "GTK+ repaint idle handler" or whatever it is. - -It is permitted to call this function multiple times, but is not -recommended due to the potential performance impact. For example, -one could change the name in the "check" function of a #GSourceFuncs -to include details like the event type in the source name. - -Use caution if changing the name while another thread may be -accessing it with g_source_get_name(); that function does not copy -the value, and changing the value will free it while the other thread -may be attempting to use it. - - - - - - - a #GSource - - - - debug name for the source - - - - - - Sets the priority of a source. While the main loop is being run, a -source will be dispatched if it is ready to be dispatched and no -sources at a higher (numerically smaller) priority are ready to be -dispatched. - -A child source always has the same priority as its parent. It is not -permitted to change the priority of a source once it has been added -as a child of another source. - - - - - - - a #GSource - - - - the new priority. - - - - - - Sets a #GSource to be dispatched when the given monotonic time is -reached (or passed). If the monotonic time is in the past (as it -always will be if @ready_time is 0) then the source will be -dispatched immediately. - -If @ready_time is -1 then the source is never woken up on the basis -of the passage of time. - -Dispatching the source does not reset the ready time. You should do -so yourself, from the source dispatch function. - -Note that if you have a pair of sources where the ready time of one -suggests that it will be delivered first but the priority for the -other suggests that it would be delivered first, and the ready time -for both sources is reached during the same main context iteration, -then the order of dispatch is undefined. - -It is a no-op to call this function on a #GSource which has already been -destroyed with g_source_destroy(). - -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. - - - - - - - a #GSource - - - - the monotonic time at which the source will be ready, - 0 for "immediately", -1 for "never" - - - - - - Decreases the reference count of a source by one. If the -resulting reference count is zero the source and associated -memory will be destroyed. - - - - - - - a #GSource - - - - - - Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. - -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). - -It is a programmer error to attempt to remove a non-existent source. - -More specifically: source IDs can be reissued after a source has been -destroyed and therefore it is never valid to use this function with a -source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the -idle may already have run and been removed by the time this function -is called on its (now invalid) source ID. This source ID may have -been reissued, leading to the operation being performed against the -wrong source. - - - For historical reasons, this function always returns %TRUE - - - - - the ID of the source to remove. - - - - - - Removes a source from the default main loop context given the -source functions and user data. If multiple sources exist with the -same source functions and user data, only one will be destroyed. - - - %TRUE if a source was found and removed. - - - - - The @source_funcs passed to g_source_new() - - - - the user data for the callback - - - - - - Removes a source from the default main loop context given the user -data for the callback. If multiple sources exist with the same user -data, only one will be destroyed. - - - %TRUE if a source was found and removed. - - - - - the user_data for the callback. - - - - - - Sets the name of a source using its ID. - -This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. - -It is a programmer error to attempt to set the name of a non-existent -source. - -More specifically: source IDs can be reissued after a source has been -destroyed and therefore it is never valid to use this function with a -source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the -idle may already have run and been removed by the time this function -is called on its (now invalid) source ID. This source ID may have -been reissued, leading to the operation being performed against the -wrong source. - - - - - - - a #GSource ID - - - - debug name for the source - - - - - - - The `GSourceCallbackFuncs` struct contains -functions for managing callback objects. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Dispose function for @source. See g_source_set_dispose_function() for -details. - - - - - - - #GSource that is currently being disposed - - - - - - This is just a placeholder for #GClosureMarshal, -which cannot be used here for dependency reasons. - - - - - - - Specifies the type of function passed to g_timeout_add(), -g_timeout_add_full(), g_idle_add(), and g_idle_add_full(). - -When calling g_source_set_callback(), you may need to cast a function of a -different type to this type. Use G_SOURCE_FUNC() to avoid warnings about -incompatible function types. - - - %FALSE if the source should be removed. #G_SOURCE_CONTINUE and -#G_SOURCE_REMOVE are more memorable names for the return value. - - - - - data passed to the function, set when the source was - created with one of the above functions - - - - - - The `GSourceFuncs` struct contains a table of -functions used to handle event sources in a generic manner. - -For idle sources, the prepare and check functions always return %TRUE -to indicate that the source is always ready to be processed. The prepare -function also returns a timeout value of 0 to ensure that the poll() call -doesn't block (since that would be time wasted which could have been spent -running the idle function). - -For timeout sources, the prepare and check functions both return %TRUE -if the timeout interval has expired. The prepare function also returns -a timeout value to ensure that the poll() call doesn't block too long -and miss the next timeout. - -For file descriptor sources, the prepare function typically returns %FALSE, -since it must wait until poll() has been called before it knows whether -any events need to be processed. It sets the returned timeout to -1 to -indicate that it doesn't mind how long the poll() call blocks. In the -check function, it tests the results of the poll() call to see if the -required condition has been met, and returns %TRUE if so. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the type of the setup function passed to g_spawn_async(), -g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very -limited ways, be used to affect the child's execution. - -On POSIX platforms, the function is called in the child after GLib -has performed all the setup it plans to perform, but before calling -exec(). Actions taken in this function will only affect the child, -not the parent. - -On Windows, the function is called in the parent. Its usefulness on -Windows is thus questionable. In many cases executing the child setup -function in the parent can have ill effects, and you should be very -careful when porting software to Windows that uses child setup -functions. - -However, even on POSIX, you are extremely limited in what you can -safely do from a #GSpawnChildSetupFunc, because any mutexes that were -held by other threads in the parent process at the time of the fork() -will still be locked in the child process, and they will never be -unlocked (since the threads that held them don't exist in the child). -POSIX allows only async-signal-safe functions (see signal(7)) to be -called in the child between fork() and exec(), which drastically limits -the usefulness of child setup functions. - -In particular, it is not safe to call any function which may -call malloc(), which includes POSIX functions such as setenv(). -If you need to set up the child environment differently from -the parent, you should use g_get_environ(), g_environ_setenv(), -and g_environ_unsetenv(), and then pass the complete environment -list to the `g_spawn...` function. - - - - - - - user data to pass to the function. - - - - - - Error codes returned by spawning processes. - - - Fork failed due to lack of memory. - - - Read or select on pipes failed. - - - Changing to working directory failed. - - - execv() returned `EACCES` - - - execv() returned `EPERM` - - - execv() returned `E2BIG` - - - deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32) - - - execv() returned `ENOEXEC` - - - execv() returned `ENAMETOOLONG` - - - execv() returned `ENOENT` - - - execv() returned `ENOMEM` - - - execv() returned `ENOTDIR` - - - execv() returned `ELOOP` - - - execv() returned `ETXTBUSY` - - - execv() returned `EIO` - - - execv() returned `ENFILE` - - - execv() returned `EMFILE` - - - execv() returned `EINVAL` - - - execv() returned `EISDIR` - - - execv() returned `ELIBBAD` - - - Some other fatal failure, - `error->message` should explain. - - - - Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). - - - no flags, default behaviour - - - the parent's open file descriptors will - be inherited by the child; otherwise all descriptors except stdin, - stdout and stderr will be closed before calling exec() in the child. - - - the child will not be automatically reaped; - you must use g_child_watch_add() yourself (or call waitpid() or handle - `SIGCHLD` yourself), or the child will become a zombie. - - - `argv[0]` need not be an absolute path, it will be - looked for in the user's `PATH`. - - - the child's standard output will be discarded, - instead of going to the same location as the parent's standard output. - - - the child's standard error will be discarded. - - - the child will inherit the parent's standard - input (by default, the child's standard input is attached to `/dev/null`). - - - the first element of `argv` is the file to - execute, while the remaining elements are the actual argument vector - to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` - as the file to execute, and passes all of `argv` to the child. - - - if `argv[0]` is not an abolute path, - it will be looked for in the `PATH` from the passed child environment. - Since: 2.34 - - - create all pipes with the `O_CLOEXEC` flag set. - Since: 2.40 - - - - A type corresponding to the appropriate struct type for the stat() -system call, depending on the platform and/or compiler being used. - -See g_stat() for more information. - - - - The GString struct contains the public fields of a GString. - - - points to the character data. It may move as text is added. - The @str field is null-terminated and so - can be used as an ordinary C string. - - - - contains the length of the string, not including the - terminating nul byte. - - - - the number of bytes that can be stored in the - string before it needs to be reallocated. May be larger than @len. - - - - Adds a string onto the end of a #GString, expanding -it if necessary. - - - @string - - - - - a #GString - - - - the string to append onto the end of @string - - - - - - Adds a byte onto the end of a #GString, expanding -it if necessary. - - - @string - - - - - a #GString - - - - the byte to append onto the end of @string - - - - - - Appends @len bytes of @val to @string. - -If @len is positive, @val may contain embedded nuls and need -not be nul-terminated. It is the caller's responsibility to -ensure that @val has at least @len addressable bytes. - -If @len is negative, @val must be nul-terminated and @len -is considered to request the entire string length. This -makes g_string_append_len() equivalent to g_string_append(). - - - @string - - - - - a #GString - - - - bytes to append - - - - number of bytes of @val to use, or -1 for all of @val - - - - - - Appends a formatted string onto the end of a #GString. -This function is similar to g_string_printf() except -that the text is appended to the #GString. - - - - - - - a #GString - - - - the string format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Converts a Unicode character into UTF-8, and appends it -to the string. - - - @string - - - - - a #GString - - - - a Unicode character - - - - - - Appends @unescaped to @string, escaped any characters that -are reserved in URIs using URI-style escape sequences. - - - @string - - - - - a #GString - - - - a string - - - - a string of reserved characters allowed - to be used, or %NULL - - - - set %TRUE if the escaped string may include UTF8 characters - - - - - - Appends a formatted string onto the end of a #GString. -This function is similar to g_string_append_printf() -except that the arguments to the format string are passed -as a va_list. - - - - - - - a #GString - - - - the string format. See the printf() documentation - - - - the list of arguments to insert in the output - - - - - - Converts all uppercase ASCII letters to lowercase ASCII letters. - - - passed-in @string pointer, with all the - uppercase characters converted to lowercase in place, - with semantics that exactly match g_ascii_tolower(). - - - - - a GString - - - - - - Converts all lowercase ASCII letters to uppercase ASCII letters. - - - passed-in @string pointer, with all the - lowercase characters converted to uppercase in place, - with semantics that exactly match g_ascii_toupper(). - - - - - a GString - - - - - - Copies the bytes from a string into a #GString, -destroying any previous contents. It is rather like -the standard strcpy() function, except that you do not -have to worry about having enough space to copy the string. - - - @string - - - - - the destination #GString. Its current contents - are destroyed. - - - - the string to copy into @string - - - - - - Converts a #GString to lowercase. - This function uses the locale-specific - tolower() function, which is almost never the right thing. - Use g_string_ascii_down() or g_utf8_strdown() instead. - - - the #GString - - - - - a #GString - - - - - - Compares two strings for equality, returning %TRUE if they are equal. -For use with #GHashTable. - - - %TRUE if the strings are the same length and contain the - same bytes - - - - - a #GString - - - - another #GString - - - - - - Removes @len bytes from a #GString, starting at position @pos. -The rest of the #GString is shifted down to fill the gap. - - - @string - - - - - a #GString - - - - the position of the content to remove - - - - the number of bytes to remove, or -1 to remove all - following bytes - - - - - - Frees the memory allocated for the #GString. -If @free_segment is %TRUE it also frees the character data. If -it's %FALSE, the caller gains ownership of the buffer and must -free it after use with g_free(). - - - the character data of @string - (i.e. %NULL if @free_segment is %TRUE) - - - - - a #GString - - - - if %TRUE, the actual character data is freed as well - - - - - - Transfers ownership of the contents of @string to a newly allocated -#GBytes. The #GString structure itself is deallocated, and it is -therefore invalid to use @string after invoking this function. - -Note that while #GString ensures that its buffer always has a -trailing nul character (not reflected in its "len"), the returned -#GBytes does not include this extra nul; i.e. it has length exactly -equal to the "len" member. - - - A newly allocated #GBytes containing contents of @string; @string itself is freed - - - - - a #GString - - - - - - Creates a hash code for @str; for use with #GHashTable. - - - hash code for @str - - - - - a string to hash - - - - - - Inserts a copy of a string into a #GString, -expanding it if necessary. - - - @string - - - - - a #GString - - - - the position to insert the copy of the string - - - - the string to insert - - - - - - Inserts a byte into a #GString, expanding it if necessary. - - - @string - - - - - a #GString - - - - the position to insert the byte - - - - the byte to insert - - - - - - Inserts @len bytes of @val into @string at @pos. - -If @len is positive, @val may contain embedded nuls and need -not be nul-terminated. It is the caller's responsibility to -ensure that @val has at least @len addressable bytes. - -If @len is negative, @val must be nul-terminated and @len -is considered to request the entire string length. - -If @pos is -1, bytes are inserted at the end of the string. - - - @string - - - - - a #GString - - - - position in @string where insertion should - happen, or -1 for at the end - - - - bytes to insert - - - - number of bytes of @val to insert, or -1 for all of @val - - - - - - Converts a Unicode character into UTF-8, and insert it -into the string at the given position. - - - @string - - - - - a #GString - - - - the position at which to insert character, or -1 - to append at the end of the string - - - - a Unicode character - - - - - - Overwrites part of a string, lengthening it if necessary. - - - @string - - - - - a #GString - - - - the position at which to start overwriting - - - - the string that will overwrite the @string starting at @pos - - - - - - Overwrites part of a string, lengthening it if necessary. -This function will work with embedded nuls. - - - @string - - - - - a #GString - - - - the position at which to start overwriting - - - - the string that will overwrite the @string starting at @pos - - - - the number of bytes to write from @val - - - - - - Adds a string on to the start of a #GString, -expanding it if necessary. - - - @string - - - - - a #GString - - - - the string to prepend on the start of @string - - - - - - Adds a byte onto the start of a #GString, -expanding it if necessary. - - - @string - - - - - a #GString - - - - the byte to prepend on the start of the #GString - - - - - - Prepends @len bytes of @val to @string. - -If @len is positive, @val may contain embedded nuls and need -not be nul-terminated. It is the caller's responsibility to -ensure that @val has at least @len addressable bytes. - -If @len is negative, @val must be nul-terminated and @len -is considered to request the entire string length. This -makes g_string_prepend_len() equivalent to g_string_prepend(). - - - @string - - - - - a #GString - - - - bytes to prepend - - - - number of bytes in @val to prepend, or -1 for all of @val - - - - - - Converts a Unicode character into UTF-8, and prepends it -to the string. - - - @string - - - - - a #GString - - - - a Unicode character - - - - - - Writes a formatted string into a #GString. -This is similar to the standard sprintf() function, -except that the #GString buffer automatically expands -to contain the results. The previous contents of the -#GString are destroyed. - - - - - - - a #GString - - - - the string format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Sets the length of a #GString. If the length is less than -the current length, the string will be truncated. If the -length is greater than the current length, the contents -of the newly added area are undefined. (However, as -always, string->str[string->len] will be a nul byte.) - - - @string - - - - - a #GString - - - - the new length - - - - - - Cuts off the end of the GString, leaving the first @len bytes. - - - @string - - - - - a #GString - - - - the new size of @string - - - - - - Converts a #GString to uppercase. - This function uses the locale-specific - toupper() function, which is almost never the right thing. - Use g_string_ascii_up() or g_utf8_strup() instead. - - - @string - - - - - a #GString - - - - - - Writes a formatted string into a #GString. -This function is similar to g_string_printf() except that -the arguments to the format string are passed as a va_list. - - - - - - - a #GString - - - - the string format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - - An opaque data structure representing String Chunks. -It should only be accessed by using the following functions. - - - Frees all strings contained within the #GStringChunk. -After calling g_string_chunk_clear() it is not safe to -access any of the strings which were contained within it. - - - - - - - a #GStringChunk - - - - - - Frees all memory allocated by the #GStringChunk. -After calling g_string_chunk_free() it is not safe to -access any of the strings which were contained within it. - - - - - - - a #GStringChunk - - - - - - Adds a copy of @string to the #GStringChunk. -It returns a pointer to the new copy of the string -in the #GStringChunk. The characters in the string -can be changed, if necessary, though you should not -change anything after the end of the string. - -Unlike g_string_chunk_insert_const(), this function -does not check for duplicates. Also strings added -with g_string_chunk_insert() will not be searched -by g_string_chunk_insert_const() when looking for -duplicates. - - - a pointer to the copy of @string within - the #GStringChunk - - - - - a #GStringChunk - - - - the string to add - - - - - - Adds a copy of @string to the #GStringChunk, unless the same -string has already been added to the #GStringChunk with -g_string_chunk_insert_const(). - -This function is useful if you need to copy a large number -of strings but do not want to waste space storing duplicates. -But you must remember that there may be several pointers to -the same string, and so any changes made to the strings -should be done very carefully. - -Note that g_string_chunk_insert_const() will not return a -pointer to a string added with g_string_chunk_insert(), even -if they do match. - - - a pointer to the new or existing copy of @string - within the #GStringChunk - - - - - a #GStringChunk - - - - the string to add - - - - - - Adds a copy of the first @len bytes of @string to the #GStringChunk. -The copy is nul-terminated. - -Since this function does not stop at nul bytes, it is the caller's -responsibility to ensure that @string has at least @len addressable -bytes. - -The characters in the returned string can be changed, if necessary, -though you should not change anything after the end of the string. - - - a pointer to the copy of @string within the #GStringChunk - - - - - a #GStringChunk - - - - bytes to insert - - - - number of bytes of @string to insert, or -1 to insert a - nul-terminated string - - - - - - Creates a new #GStringChunk. - - - a new #GStringChunk - - - - - the default size of the blocks of memory which are - allocated to store the strings. If a particular string - is larger than this default size, a larger block of - memory will be allocated for it. - - - - - - - Creates a unique temporary directory for each unit test and uses -g_set_user_dirs() to set XDG directories to point into subdirectories of it -for the duration of the unit test. The directory tree is cleaned up after the -test finishes successfully. Note that this doesn’t take effect until -g_test_run() is called, so calls to (for example) g_get_user_home_dir() will -return the system-wide value when made in a test program’s main() function. - -The following functions will return subdirectories of the temporary directory -when this option is used. The specific subdirectory paths in use are not -guaranteed to be stable API — always use a getter function to retrieve them. - - - g_get_home_dir() - - g_get_user_cache_dir() - - g_get_system_config_dirs() - - g_get_user_config_dir() - - g_get_system_data_dirs() - - g_get_user_data_dir() - - g_get_user_runtime_dir() - -The subdirectories may not be created by the test harness; as with normal -calls to functions like g_get_user_cache_dir(), the caller must be prepared -to create the directory if it doesn’t exist. - - - - - Evaluates to a time span of one day. - - - - - Evaluates to a time span of one hour. - - - - - Evaluates to a time span of one millisecond. - - - - - Evaluates to a time span of one minute. - - - - - Evaluates to a time span of one second. - - - - - Works like g_mutex_trylock(), but for a lock defined with -#G_LOCK_DEFINE. - - - - the name of the lock - - - - - An opaque structure representing a test case. - - - - - - - - - - - - - - - - - - - - - - - - - The type used for test case functions that take an extra pointer -argument. - - - - - - - the data provided when registering the test - - - - - - The type of file to return the filename for, when used with -g_test_build_filename(). - -These two options correspond rather directly to the 'dist' and -'built' terminology that automake uses and are explicitly used to -distinguish between the 'srcdir' and 'builddir' being separate. All -files in your project should either be dist (in the -`EXTRA_DIST` or `dist_schema_DATA` -sense, in which case they will always be in the srcdir) or built (in -the `BUILT_SOURCES` sense, in which case they will -always be in the builddir). - -Note: as a general rule of automake, files that are generated only as -part of the build-from-git process (but then are distributed with the -tarball) always go in srcdir (even if doing a srcdir != builddir -build from git) and are considered as distributed files. - - - a file that was included in the distribution tarball - - - a file that was built on the compiling machine - - - - The type used for functions that operate on test fixtures. This is -used for the fixture setup and teardown functions as well as for the -testcases themselves. - -@user_data is a pointer to the data that was given when registering -the test case. - -@fixture will be a pointer to the area of memory allocated by the -test framework, of the size requested. If the requested size was -zero then @fixture will be equal to @user_data. - - - - - - - the test fixture - - - - the data provided when registering the test - - - - - - The type used for test case functions. - - - - - - - - - - - - - - - - - Internal function for gtester to free test log messages, no ABI guarantees provided. - - - - - - - - - - - - Internal function for gtester to retrieve test log messages, no ABI guarantees provided. - - - - - - - - - - - - Internal function for gtester to decode test log messages, no ABI guarantees provided. - - - - - - - - - - - - - - - - - - Internal function for gtester to decode test log messages, no ABI guarantees provided. - - - - - - - - Specifies the prototype of fatal log handler functions. - - - %TRUE if the program should abort, %FALSE otherwise - - - - - the log domain of the message - - - - the log level of the message (including the fatal and recursion flags) - - - - the message to process - - - - user data, set in g_test_log_set_fatal_handler() - - - - - - - - - - - - - - - - - - - - - - - Internal function for gtester to free test log messages, no ABI guarantees provided. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags to pass to g_test_trap_subprocess() to control input and output. - -Note that in contrast with g_test_trap_fork(), the default is to -not show stdout and stderr. - - - If this flag is given, the child - process will inherit the parent's stdin. Otherwise, the child's - stdin is redirected to `/dev/null`. - - - If this flag is given, the child - process will inherit the parent's stdout. Otherwise, the child's - stdout will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stdout(). - - - If this flag is given, the child - process will inherit the parent's stderr. Otherwise, the child's - stderr will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stderr(). - - - - An opaque structure representing a test suite. - - - Adds @test_case to @suite. - - - - - - - a #GTestSuite - - - - a #GTestCase - - - - - - Adds @nestedsuite to @suite. - - - - - - - a #GTestSuite - - - - another #GTestSuite - - - - - - - Test traps are guards around forked tests. -These flags determine what traps to set. - #GTestTrapFlags is used only with g_test_trap_fork(), -which is deprecated. g_test_trap_subprocess() uses -#GTestSubprocessFlags. - - - Redirect stdout of the test child to - `/dev/null` so it cannot be observed on the console during test - runs. The actual output is still captured though to allow later - tests with g_test_trap_assert_stdout(). - - - Redirect stderr of the test child to - `/dev/null` so it cannot be observed on the console during test - runs. The actual output is still captured though to allow later - tests with g_test_trap_assert_stderr(). - - - If this flag is given, stdin of the - child process is shared with stdin of its parent process. - It is redirected to `/dev/null` otherwise. - - - - The #GThread struct represents a running thread. This struct -is returned by g_thread_new() or g_thread_try_new(). You can -obtain the #GThread struct representing the current thread by -calling g_thread_self(). - -GThread is refcounted, see g_thread_ref() and g_thread_unref(). -The thread represented by it holds a reference while it is running, -and g_thread_join() consumes the reference that it is given, so -it is normally not necessary to manage GThread references -explicitly. - -The structure is opaque -- none of its fields may be directly -accessed. - - - This function creates a new thread. The new thread starts by invoking -@func with the argument data. The thread will run until @func returns -or until g_thread_exit() is called from the new thread. The return value -of @func becomes the return value of the thread, which can be obtained -with g_thread_join(). - -The @name can be useful for discriminating threads in a debugger. -It is not used for other purposes and does not have to be unique. -Some systems restrict the length of @name to 16 bytes. - -If the thread can not be created the program aborts. See -g_thread_try_new() if you want to attempt to deal with failures. - -If you are using threads to offload (potentially many) short-lived tasks, -#GThreadPool may be more appropriate than manually spawning and tracking -multiple #GThreads. - -To free the struct returned by this function, use g_thread_unref(). -Note that g_thread_join() implicitly unrefs the #GThread as well. - -New threads by default inherit their scheduler policy (POSIX) or thread -priority (Windows) of the thread creating the new thread. - -This behaviour changed in GLib 2.64: before threads on Windows were not -inheriting the thread priority but were spawned with the default priority. -Starting with GLib 2.64 the behaviour is now consistent between Windows and -POSIX and all threads inherit their parent thread's priority. - - - the new #GThread - - - - - an (optional) name for the new thread - - - - a function to execute in the new thread - - - - an argument to supply to the new thread - - - - - - This function is the same as g_thread_new() except that -it allows for the possibility of failure. - -If a thread can not be created (due to resource limits), -@error is set and %NULL is returned. - - - the new #GThread, or %NULL if an error occurred - - - - - an (optional) name for the new thread - - - - a function to execute in the new thread - - - - an argument to supply to the new thread - - - - - - Waits until @thread finishes, i.e. the function @func, as -given to g_thread_new(), returns or g_thread_exit() is called. -If @thread has already terminated, then g_thread_join() -returns immediately. - -Any thread can wait for any other thread by calling g_thread_join(), -not just its 'creator'. Calling g_thread_join() from multiple threads -for the same @thread leads to undefined behaviour. - -The value returned by @func or given to g_thread_exit() is -returned by this function. - -g_thread_join() consumes the reference to the passed-in @thread. -This will usually cause the #GThread struct and associated resources -to be freed. Use g_thread_ref() to obtain an extra reference if you -want to keep the GThread alive beyond the g_thread_join() call. - - - the return value of the thread - - - - - a #GThread - - - - - - Increase the reference count on @thread. - - - a new reference to @thread - - - - - a #GThread - - - - - - Decrease the reference count on @thread, possibly freeing all -resources associated with it. - -Note that each thread holds a reference to its #GThread while -it is running, so it is safe to drop your own reference to it -if you don't need it anymore. - - - - - - - a #GThread - - - - - - - - - - - Terminates the current thread. - -If another thread is waiting for us using g_thread_join() then the -waiting thread will be woken up and get @retval as the return value -of g_thread_join(). - -Calling g_thread_exit() with a parameter @retval is equivalent to -returning @retval from the function @func, as given to g_thread_new(). - -You must only call g_thread_exit() from a thread that you created -yourself with g_thread_new() or related APIs. You must not call -this function from a thread created with another threading library -or or from within a #GThreadPool. - - - - - - - the return value of this thread - - - - - - This function returns the #GThread corresponding to the -current thread. Note that this function does not increase -the reference count of the returned struct. - -This function will return a #GThread even for threads that -were not created by GLib (i.e. those created by other threading -APIs). This may be useful for thread identification purposes -(i.e. comparisons) but you must not use GLib functions (such -as g_thread_join()) on these threads. - - - the #GThread representing the current thread - - - - - Causes the calling thread to voluntarily relinquish the CPU, so -that other threads can run. - -This function is often used as a method to make busy wait less evil. - - - - - - - - Possible errors of thread related functions. - - - a thread couldn't be created due to resource - shortage. Try again later. - - - - Specifies the type of the @func functions passed to g_thread_new() -or g_thread_try_new(). - - - the return value of the thread - - - - - data passed to the thread - - - - - - The #GThreadPool struct represents a thread pool. It has three -public read-only members, but the underlying struct is bigger, -so you must not copy this struct. - - - the function to execute in the threads of this pool - - - - the user data for the threads of this pool - - - - are all threads exclusive to this pool - - - - Frees all resources allocated for @pool. - -If @immediate is %TRUE, no new task is processed for @pool. -Otherwise @pool is not freed before the last task is processed. -Note however, that no thread of this pool is interrupted while -processing a task. Instead at least all still running threads -can finish their tasks before the @pool is freed. - -If @wait_ is %TRUE, the functions does not return before all -tasks to be processed (dependent on @immediate, whether all -or only the currently running) are ready. -Otherwise the function returns immediately. - -After calling this function @pool must not be used anymore. - - - - - - - a #GThreadPool - - - - should @pool shut down immediately? - - - - should the function wait for all tasks to be finished? - - - - - - Returns the maximal number of threads for @pool. - - - the maximal number of threads - - - - - a #GThreadPool - - - - - - Returns the number of threads currently running in @pool. - - - the number of threads currently running - - - - - a #GThreadPool - - - - - - Moves the item to the front of the queue of unprocessed -items, so that it will be processed next. - - - %TRUE if the item was found and moved - - - - - a #GThreadPool - - - - an unprocessed item in the pool - - - - - - Inserts @data into the list of tasks to be executed by @pool. - -When the number of currently running threads is lower than the -maximal allowed number of threads, a new thread is started (or -reused) with the properties given to g_thread_pool_new(). -Otherwise, @data stays in the queue until a thread in this pool -finishes its previous task and processes @data. - -@error can be %NULL to ignore errors, or non-%NULL to report -errors. An error can only occur when a new thread couldn't be -created. In that case @data is simply appended to the queue of -work to do. - -Before version 2.32, this function did not return a success status. - - - %TRUE on success, %FALSE if an error occurred - - - - - a #GThreadPool - - - - a new task for @pool - - - - - - Sets the maximal allowed number of threads for @pool. -A value of -1 means that the maximal number of threads -is unlimited. If @pool is an exclusive thread pool, setting -the maximal number of threads to -1 is not allowed. - -Setting @max_threads to 0 means stopping all work for @pool. -It is effectively frozen until @max_threads is set to a non-zero -value again. - -A thread is never terminated while calling @func, as supplied by -g_thread_pool_new(). Instead the maximal number of threads only -has effect for the allocation of new threads in g_thread_pool_push(). -A new thread is allocated, whenever the number of currently -running threads in @pool is smaller than the maximal number. - -@error can be %NULL to ignore errors, or non-%NULL to report -errors. An error can only occur when a new thread couldn't be -created. - -Before version 2.32, this function did not return a success status. - - - %TRUE on success, %FALSE if an error occurred - - - - - a #GThreadPool - - - - a new maximal number of threads for @pool, - or -1 for unlimited - - - - - - Sets the function used to sort the list of tasks. This allows the -tasks to be processed by a priority determined by @func, and not -just in the order in which they were added to the pool. - -Note, if the maximum number of threads is more than 1, the order -that threads are executed cannot be guaranteed 100%. Threads are -scheduled by the operating system and are executed at random. It -cannot be assumed that threads are executed in the order they are -created. - - - - - - - a #GThreadPool - - - - the #GCompareDataFunc used to sort the list of tasks. - This function is passed two tasks. It should return - 0 if the order in which they are handled does not matter, - a negative value if the first task should be processed before - the second or a positive value if the second task should be - processed first. - - - - user data passed to @func - - - - - - Returns the number of tasks still unprocessed in @pool. - - - the number of unprocessed tasks - - - - - a #GThreadPool - - - - - - This function will return the maximum @interval that a -thread will wait in the thread pool for new tasks before -being stopped. - -If this function returns 0, threads waiting in the thread -pool for new work are not stopped. - - - the maximum @interval (milliseconds) to wait - for new tasks in the thread pool before stopping the - thread - - - - - Returns the maximal allowed number of unused threads. - - - the maximal number of unused threads - - - - - Returns the number of currently unused threads. - - - the number of currently unused threads - - - - - This function creates a new thread pool. - -Whenever you call g_thread_pool_push(), either a new thread is -created or an unused one is reused. At most @max_threads threads -are running concurrently for this thread pool. @max_threads = -1 -allows unlimited threads to be created for this thread pool. The -newly created or reused thread now executes the function @func -with the two arguments. The first one is the parameter to -g_thread_pool_push() and the second one is @user_data. - -The parameter @exclusive determines whether the thread pool owns -all threads exclusive or shares them with other thread pools. -If @exclusive is %TRUE, @max_threads threads are started -immediately and they will run exclusively for this thread pool -until it is destroyed by g_thread_pool_free(). If @exclusive is -%FALSE, threads are created when needed and shared between all -non-exclusive thread pools. This implies that @max_threads may -not be -1 for exclusive thread pools. Besides, exclusive thread -pools are not affected by g_thread_pool_set_max_idle_time() -since their threads are never considered idle and returned to the -global pool. - -@error can be %NULL to ignore errors, or non-%NULL to report -errors. An error can only occur when @exclusive is set to %TRUE -and not all @max_threads threads could be created. -See #GThreadError for possible errors that may occur. -Note, even in case of error a valid #GThreadPool is returned. - - - the new #GThreadPool - - - - - a function to execute in the threads of the new thread pool - - - - user data that is handed over to @func every time it - is called - - - - the maximal number of threads to execute concurrently - in the new thread pool, -1 means no limit - - - - should this thread pool be exclusive? - - - - - - This function will set the maximum @interval that a thread -waiting in the pool for new tasks can be idle for before -being stopped. This function is similar to calling -g_thread_pool_stop_unused_threads() on a regular timeout, -except this is done on a per thread basis. - -By setting @interval to 0, idle threads will not be stopped. - -The default value is 15000 (15 seconds). - - - - - - - the maximum @interval (in milliseconds) - a thread can be idle - - - - - - Sets the maximal number of unused threads to @max_threads. -If @max_threads is -1, no limit is imposed on the number -of unused threads. - -The default value is 2. - - - - - - - maximal number of unused threads - - - - - - Stops all currently unused threads. This does not change the -maximal number of unused threads. This function can be used to -regularly stop all unused threads e.g. from g_timeout_add(). - - - - - - - - Disambiguates a given time in two ways. - -First, specifies if the given time is in universal or local time. - -Second, if the time is in local time, specifies if it is local -standard time or local daylight time. This is important for the case -where the same local time occurs twice (during daylight savings time -transitions, for example). - - - the time is in local standard time - - - the time is in local daylight time - - - the time is in UTC - - - - Represents a precise time, with seconds and microseconds. -Similar to the struct timeval returned by the gettimeofday() -UNIX system call. - -GLib is attempting to unify around the use of 64-bit integers to -represent microsecond-precision time. As such, this type will be -removed from a future version of GLib. A consequence of using `glong` for -`tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 -problem. - Use #GDateTime or #guint64 instead. - - - seconds - - - - microseconds - - - - Adds the given number of microseconds to @time_. @microseconds can -also be negative to decrease the value of @time_. - #GTimeVal is not year-2038-safe. Use `guint64` for - representing microseconds since the epoch, or use #GDateTime. - - - - - - - a #GTimeVal - - - - number of microseconds to add to @time - - - - - - Converts @time_ into an RFC 3339 encoded string, relative to the -Coordinated Universal Time (UTC). This is one of the many formats -allowed by ISO 8601. - -ISO 8601 allows a large number of date/time formats, with or without -punctuation and optional elements. The format returned by this function -is a complete date and time, with optional punctuation included, the -UTC time zone represented as "Z", and the @tv_usec part included if -and only if it is nonzero, i.e. either -"YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". - -This corresponds to the Internet date/time format defined by -[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), -and to either of the two most-precise formats defined by -the W3C Note -[Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). -Both of these documents are profiles of ISO 8601. - -Use g_date_time_format() or g_strdup_printf() if a different -variation of ISO 8601 format is required. - -If @time_ represents a date which is too large to fit into a `struct tm`, -%NULL will be returned. This is platform dependent. Note also that since -`GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it -is subject to the year 2038 problem. Accordingly, since GLib 2.62, this -function has been deprecated. Equivalent functionality is available using: -|[ -GDateTime *dt = g_date_time_new_from_unix_utc (time_val); -iso8601_string = g_date_time_format_iso8601 (dt); -g_date_time_unref (dt); -]| - -The return value of g_time_val_to_iso8601() has been nullable since GLib -2.54; before then, GLib would crash under the same conditions. - #GTimeVal is not year-2038-safe. Use - g_date_time_format_iso8601(dt) instead. - - - a newly allocated string containing an ISO 8601 date, - or %NULL if @time_ was too large - - - - - a #GTimeVal - - - - - - Converts a string containing an ISO 8601 encoded date and time -to a #GTimeVal and puts it into @time_. - -@iso_date must include year, month, day, hours, minutes, and -seconds. It can optionally include fractions of a second and a time -zone indicator. (In the absence of any time zone indication, the -timestamp is assumed to be in local time.) - -Any leading or trailing space in @iso_date is ignored. - -This function was deprecated, along with #GTimeVal itself, in GLib 2.62. -Equivalent functionality is available using code like: -|[ -GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL); -gint64 time_val = g_date_time_to_unix (dt); -g_date_time_unref (dt); -]| - #GTimeVal is not year-2038-safe. Use - g_date_time_new_from_iso8601() instead. - - - %TRUE if the conversion was successful. - - - - - an ISO 8601 encoded date string - - - - a #GTimeVal - - - - - - - #GTimeZone is an opaque structure whose members cannot be accessed -directly. - - - Creates a #GTimeZone corresponding to @identifier. - -@identifier can either be an RFC3339/ISO 8601 time offset or -something that would pass as a valid value for the `TZ` environment -variable (including %NULL). - -In Windows, @identifier can also be the unlocalized name of a time -zone for standard time, for example "Pacific Standard Time". - -Valid RFC3339 time offsets are `"Z"` (for UTC) or -`"±hh:mm"`. ISO 8601 additionally specifies -`"±hhmm"` and `"±hh"`. Offsets are -time values to be added to Coordinated Universal Time (UTC) to get -the local time. - -In UNIX, the `TZ` environment variable typically corresponds -to the name of a file in the zoneinfo database, an absolute path to a file -somewhere else, or a string in -"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. -There are no spaces in the specification. The name of standard -and daylight savings time zone must be three or more alphabetic -characters. Offsets are time values to be added to local time to -get Coordinated Universal Time (UTC) and should be -`"[±]hh[[:]mm[:ss]]"`. Dates are either -`"Jn"` (Julian day with n between 1 and 365, leap -years not counted), `"n"` (zero-based Julian day -with n between 0 and 365) or `"Mm.w.d"` (day d -(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day -0 is a Sunday). Times are in local wall clock time, the default is -02:00:00. - -In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also -accepts POSIX format. The Windows format uses US rules for all time -zones; daylight savings time is 60 minutes behind the standard time -with date and time of change taken from Pacific Standard Time. -Offsets are time values to be added to the local time to get -Coordinated Universal Time (UTC). - -g_time_zone_new_local() calls this function with the value of the -`TZ` environment variable. This function itself is independent of -the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` -will be consulted to discover the correct time zone on UNIX and the -registry will be consulted or GetTimeZoneInformation() will be used -to get the local time zone on Windows. - -If intervals are not available, only time zone rules from `TZ` -environment variable or other means, then they will be computed -from year 1900 to 2037. If the maximum year for the rules is -available and it is greater than 2037, then it will followed -instead. - -See -[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) -for a precise definition of valid RFC3339 time offsets -(the `time-offset` expansion) and ISO 8601 for the -full list of valid time offsets. See -[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) -for an explanation of the possible -values of the `TZ` environment variable. See -[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) -for the list of time zones on Windows. - -You should release the return value by calling g_time_zone_unref() -when you are done with it. - - - the requested timezone - - - - - a timezone identifier - - - - - - Creates a #GTimeZone corresponding to local time. The local time -zone may change between invocations to this function; for example, -if the system administrator changes it. - -This is equivalent to calling g_time_zone_new() with the value of -the `TZ` environment variable (including the possibility of %NULL). - -You should release the return value by calling g_time_zone_unref() -when you are done with it. - - - the local timezone - - - - - Creates a #GTimeZone corresponding to the given constant offset from UTC, -in seconds. - -This is equivalent to calling g_time_zone_new() with a string in the form -`[+|-]hh[:mm[:ss]]`. - - - a timezone at the given offset from UTC - - - - - offset to UTC, in seconds - - - - - - Creates a #GTimeZone corresponding to UTC. - -This is equivalent to calling g_time_zone_new() with a value like -"Z", "UTC", "+00", etc. - -You should release the return value by calling g_time_zone_unref() -when you are done with it. - - - the universal timezone - - - - - Finds an interval within @tz that corresponds to the given @time_, -possibly adjusting @time_ if required to fit into an interval. -The meaning of @time_ depends on @type. - -This function is similar to g_time_zone_find_interval(), with the -difference that it always succeeds (by making the adjustments -described below). - -In any of the cases where g_time_zone_find_interval() succeeds then -this function returns the same value, without modifying @time_. - -This function may, however, modify @time_ in order to deal with -non-existent times. If the non-existent local @time_ of 02:30 were -requested on March 14th 2010 in Toronto then this function would -adjust @time_ to be 03:00 and return the interval containing the -adjusted time. - - - the interval containing @time_, never -1 - - - - - a #GTimeZone - - - - the #GTimeType of @time_ - - - - a pointer to a number of seconds since January 1, 1970 - - - - - - Finds an interval within @tz that corresponds to the given @time_. -The meaning of @time_ depends on @type. - -If @type is %G_TIME_TYPE_UNIVERSAL then this function will always -succeed (since universal time is monotonic and continuous). - -Otherwise @time_ is treated as local time. The distinction between -%G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in -the case that the given @time_ is ambiguous. In Toronto, for example, -01:30 on November 7th 2010 occurred twice (once inside of daylight -savings time and the next, an hour later, outside of daylight savings -time). In this case, the different value of @type would result in a -different interval being returned. - -It is still possible for this function to fail. In Toronto, for -example, 02:00 on March 14th 2010 does not exist (due to the leap -forward to begin daylight savings time). -1 is returned in that -case. - - - the interval containing @time_, or -1 in case of failure - - - - - a #GTimeZone - - - - the #GTimeType of @time_ - - - - a number of seconds since January 1, 1970 - - - - - - Determines the time zone abbreviation to be used during a particular -@interval of time in the time zone @tz. - -For example, in Toronto this is currently "EST" during the winter -months and "EDT" during the summer months when daylight savings time -is in effect. - - - the time zone abbreviation, which belongs to @tz - - - - - a #GTimeZone - - - - an interval within the timezone - - - - - - Get the identifier of this #GTimeZone, as passed to g_time_zone_new(). -If the identifier passed at construction time was not recognised, `UTC` will -be returned. If it was %NULL, the identifier of the local timezone at -construction time will be returned. - -The identifier will be returned in the same format as provided at -construction time: if provided as a time offset, that will be returned by -this function. - - - identifier for this timezone - - - - - a #GTimeZone - - - - - - Determines the offset to UTC in effect during a particular @interval -of time in the time zone @tz. - -The offset is the number of seconds that you add to UTC time to -arrive at local time for @tz (ie: negative numbers for time zones -west of GMT, positive numbers for east). - - - the number of seconds that should be added to UTC to get the - local time in @tz - - - - - a #GTimeZone - - - - an interval within the timezone - - - - - - Determines if daylight savings time is in effect during a particular -@interval of time in the time zone @tz. - - - %TRUE if daylight savings time is in effect - - - - - a #GTimeZone - - - - an interval within the timezone - - - - - - Increases the reference count on @tz. - - - a new reference to @tz. - - - - - a #GTimeZone - - - - - - Decreases the reference count on @tz. - - - - - - - a #GTimeZone - - - - - - - Opaque datatype that records a start time. - - - Resumes a timer that has previously been stopped with -g_timer_stop(). g_timer_stop() must be called before using this -function. - - - - - - - a #GTimer. - - - - - - Destroys a timer, freeing associated resources. - - - - - - - a #GTimer to destroy. - - - - - - If @timer has been started but not stopped, obtains the time since -the timer was started. If @timer has been stopped, obtains the -elapsed time between the time it was started and the time it was -stopped. The return value is the number of seconds elapsed, -including any fractional part. The @microseconds out parameter is -essentially useless. - - - seconds elapsed as a floating point value, including any - fractional part. - - - - - a #GTimer. - - - - return location for the fractional part of seconds - elapsed, in microseconds (that is, the total number - of microseconds elapsed, modulo 1000000), or %NULL - - - - - - Exposes whether the timer is currently active. - - - %TRUE if the timer is running, %FALSE otherwise - - - - - a #GTimer. - - - - - - This function is useless; it's fine to call g_timer_start() on an -already-started timer to reset the start time, so g_timer_reset() -serves no purpose. - - - - - - - a #GTimer. - - - - - - Marks a start time, so that future calls to g_timer_elapsed() will -report the time since g_timer_start() was called. g_timer_new() -automatically marks the start time, so no need to call -g_timer_start() immediately after creating the timer. - - - - - - - a #GTimer. - - - - - - Marks an end time, so calls to g_timer_elapsed() will return the -difference between this end time and the start time. - - - - - - - a #GTimer. - - - - - - Creates a new timer, and starts timing (i.e. g_timer_start() is -implicitly called for you). - - - a new #GTimer. - - - - - - The possible types of token returned from each -g_scanner_get_next_token() call. - - - the end of the file - - - a '(' character - - - a ')' character - - - a '{' character - - - a '}' character - - - a '[' character - - - a ']' character - - - a '=' character - - - a ',' character - - - not a token - - - an error occurred - - - a character - - - a binary integer - - - an octal integer - - - an integer - - - a hex integer - - - a floating point number - - - a string - - - a symbol - - - an identifier - - - a null identifier - - - one line comment - - - multi line comment - - - - A union holding the value of the token. - - - token symbol value - - - - token identifier value - - - - token binary integer value - - - - octal integer value - - - - integer value - - - - 64-bit integer value - - - - floating point value - - - - hex integer value - - - - string value - - - - comment value - - - - character value - - - - error value - - - - - The type of functions which are used to translate user-visible -strings, for <option>--help</option> output. - - - a translation of the string for the current locale. - The returned string is owned by GLib and must not be freed. - - - - - the untranslated string - - - - user data specified when installing the function, e.g. - in g_option_group_set_translate_func() - - - - - - Each piece of memory that is pushed onto the stack -is cast to a GTrashStack*. - #GTrashStack is deprecated without replacement - - - pointer to the previous element of the stack, - gets stored in the first `sizeof (gpointer)` - bytes of the element - - - - Returns the height of a #GTrashStack. - -Note that execution of this function is of O(N) complexity -where N denotes the number of items on the stack. - #GTrashStack is deprecated without replacement - - - the height of the stack - - - - - a #GTrashStack - - - - - - Returns the element at the top of a #GTrashStack -which may be %NULL. - #GTrashStack is deprecated without replacement - - - the element at the top of the stack - - - - - a #GTrashStack - - - - - - Pops a piece of memory off a #GTrashStack. - #GTrashStack is deprecated without replacement - - - the element at the top of the stack - - - - - a #GTrashStack - - - - - - Pushes a piece of memory onto a #GTrashStack. - #GTrashStack is deprecated without replacement - - - - - - - a #GTrashStack - - - - the piece of memory to push on the stack - - - - - - - Specifies which nodes are visited during several of the tree -functions, including g_node_traverse() and g_node_find(). - - - only leaf nodes should be visited. This name has - been introduced in 2.6, for older version use - %G_TRAVERSE_LEAFS. - - - only non-leaf nodes should be visited. This - name has been introduced in 2.6, for older - version use %G_TRAVERSE_NON_LEAFS. - - - all nodes should be visited. - - - a mask of all traverse flags. - - - identical to %G_TRAVERSE_LEAVES. - - - identical to %G_TRAVERSE_NON_LEAVES. - - - - Specifies the type of function passed to g_tree_traverse(). It is -passed the key and value of each node, together with the @user_data -parameter passed to g_tree_traverse(). If the function returns -%TRUE, the traversal is stopped. - - - %TRUE to stop the traversal - - - - - a key of a #GTree node - - - - the value corresponding to the key - - - - user data passed to g_tree_traverse() - - - - - - Specifies the type of traveral performed by g_tree_traverse(), -g_node_traverse() and g_node_find(). The different orders are -illustrated here: -- In order: A, B, C, D, E, F, G, H, I - ![](Sorted_binary_tree_inorder.svg) -- Pre order: F, B, A, D, C, E, G, I, H - ![](Sorted_binary_tree_preorder.svg) -- Post order: A, C, E, D, B, H, I, G, F - ![](Sorted_binary_tree_postorder.svg) -- Level order: F, B, G, A, D, I, C, E, H - ![](Sorted_binary_tree_breadth-first_traversal.svg) - - - vists a node's left child first, then the node itself, - then its right child. This is the one to use if you - want the output sorted according to the compare - function. - - - visits a node, then its children. - - - visits the node's children, then the node itself. - - - is not implemented for - [balanced binary trees][glib-Balanced-Binary-Trees]. - For [n-ary trees][glib-N-ary-Trees], it - vists the root node first, then its children, then - its grandchildren, and so on. Note that this is less - efficient than the other orders. - - - - The GTree struct is an opaque data structure representing a -[balanced binary tree][glib-Balanced-Binary-Trees]. It should be -accessed only by using the following functions. - - - Removes all keys and values from the #GTree and decreases its -reference count by one. If keys and/or values are dynamically -allocated, you should either free them first or create the #GTree -using g_tree_new_full(). In the latter case the destroy functions -you supplied will be called on all keys and values before destroying -the #GTree. - - - - - - - a #GTree - - - - - - Calls the given function for each of the key/value pairs in the #GTree. -The function is passed the key and value of each pair, and the given -@data parameter. The tree is traversed in sorted order. - -The tree may not be modified while iterating over it (you can't -add/remove items). To remove all items matching a predicate, you need -to add each item to a list in your #GTraverseFunc as you walk over -the tree, then walk the list and remove each item. - - - - - - - a #GTree - - - - the function to call for each node visited. - If this function returns %TRUE, the traversal is stopped. - - - - user data to pass to the function - - - - - - Gets the height of a #GTree. - -If the #GTree contains no nodes, the height is 0. -If the #GTree contains only one root node the height is 1. -If the root node has children the height is 2, etc. - - - the height of @tree - - - - - a #GTree - - - - - - Inserts a key/value pair into a #GTree. - -If the given key already exists in the #GTree its corresponding value -is set to the new value. If you supplied a @value_destroy_func when -creating the #GTree, the old value is freed using that function. If -you supplied a @key_destroy_func when creating the #GTree, the passed -key is freed using that function. - -The tree is automatically 'balanced' as new key/value pairs are added, -so that the distance from the root to every leaf is as small as possible. - - - - - - - a #GTree - - - - the key to insert - - - - the value corresponding to the key - - - - - - Gets the value corresponding to the given key. Since a #GTree is -automatically balanced as key/value pairs are added, key lookup -is O(log n) (where n is the number of key/value pairs in the tree). - - - the value corresponding to the key, or %NULL - if the key was not found - - - - - a #GTree - - - - the key to look up - - - - - - Looks up a key in the #GTree, returning the original key and the -associated value. This is useful if you need to free the memory -allocated for the original key, for example before calling -g_tree_remove(). - - - %TRUE if the key was found in the #GTree - - - - - a #GTree - - - - the key to look up - - - - returns the original key - - - - returns the value associated with the key - - - - - - Gets the number of nodes in a #GTree. - - - the number of nodes in @tree - - - - - a #GTree - - - - - - Increments the reference count of @tree by one. - -It is safe to call this function from any thread. - - - the passed in #GTree - - - - - a #GTree - - - - - - Removes a key/value pair from a #GTree. - -If the #GTree was created using g_tree_new_full(), the key and value -are freed using the supplied destroy functions, otherwise you have to -make sure that any dynamically allocated values are freed yourself. -If the key does not exist in the #GTree, the function does nothing. - - - %TRUE if the key was found (prior to 2.8, this function - returned nothing) - - - - - a #GTree - - - - the key to remove - - - - - - Inserts a new key and value into a #GTree similar to g_tree_insert(). -The difference is that if the key already exists in the #GTree, it gets -replaced by the new key. If you supplied a @value_destroy_func when -creating the #GTree, the old value is freed using that function. If you -supplied a @key_destroy_func when creating the #GTree, the old key is -freed using that function. - -The tree is automatically 'balanced' as new key/value pairs are added, -so that the distance from the root to every leaf is as small as possible. - - - - - - - a #GTree - - - - the key to insert - - - - the value corresponding to the key - - - - - - Searches a #GTree using @search_func. - -The @search_func is called with a pointer to the key of a key/value -pair in the tree, and the passed in @user_data. If @search_func returns -0 for a key/value pair, then the corresponding value is returned as -the result of g_tree_search(). If @search_func returns -1, searching -will proceed among the key/value pairs that have a smaller key; if -@search_func returns 1, searching will proceed among the key/value -pairs that have a larger key. - - - the value corresponding to the found key, or %NULL - if the key was not found - - - - - a #GTree - - - - a function used to search the #GTree - - - - the data passed as the second argument to @search_func - - - - - - Removes a key and its associated value from a #GTree without calling -the key and value destroy functions. - -If the key does not exist in the #GTree, the function does nothing. - - - %TRUE if the key was found (prior to 2.8, this function - returned nothing) - - - - - a #GTree - - - - the key to remove - - - - - - Calls the given function for each node in the #GTree. - The order of a balanced tree is somewhat arbitrary. - If you just want to visit all nodes in sorted order, use - g_tree_foreach() instead. If you really need to visit nodes in - a different order, consider using an [n-ary tree][glib-N-ary-Trees]. - - - - - - - a #GTree - - - - the function to call for each node visited. If this - function returns %TRUE, the traversal is stopped. - - - - the order in which nodes are visited, one of %G_IN_ORDER, - %G_PRE_ORDER and %G_POST_ORDER - - - - user data to pass to the function - - - - - - Decrements the reference count of @tree by one. -If the reference count drops to 0, all keys and values will -be destroyed (if destroy functions were specified) and all -memory allocated by @tree will be released. - -It is safe to call this function from any thread. - - - - - - - a #GTree - - - - - - Creates a new #GTree. - - - a newly allocated #GTree - - - - - the function used to order the nodes in the #GTree. - It should return values similar to the standard strcmp() function - - 0 if the two arguments are equal, a negative value if the first argument - comes before the second, or a positive value if the first argument comes - after the second. - - - - - - Creates a new #GTree like g_tree_new() and allows to specify functions -to free the memory allocated for the key and value that get called when -removing the entry from the #GTree. - - - a newly allocated #GTree - - - - - qsort()-style comparison function - - - - data to pass to comparison function - - - - a function to free the memory allocated for the key - used when removing the entry from the #GTree or %NULL if you don't - want to supply such a function - - - - a function to free the memory allocated for the - value used when removing the entry from the #GTree or %NULL if you - don't want to supply such a function - - - - - - Creates a new #GTree with a comparison function that accepts user data. -See g_tree_new() for more details. - - - a newly allocated #GTree - - - - - qsort()-style comparison function - - - - data to pass to comparison function - - - - - - - This macro can be used to mark a function declaration as unavailable. -It must be placed before the function declaration. Use of a function -that has been annotated with this macros will produce a compiler warning. - - - - the major version that introduced the symbol - - - the minor version that introduced the symbol - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The maximum length (in codepoints) of a compatibility or canonical -decomposition of a single Unicode character. - -This is as defined by Unicode 6.1. - - - - - Hints the compiler that the expression is unlikely to evaluate to -a true value. The compiler may use this information for optimizations. - -|[<!-- language="C" --> -if (G_UNLIKELY (random () == 1)) - g_print ("a random one"); -]| - - - - the expression - - - - - Works like g_mutex_unlock(), but for a lock defined with -#G_LOCK_DEFINE. - - - - the name of the lock - - - - - Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". - - - - - Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". - - - - - Number of microseconds in one second (1 million). -This macro is provided for code readability. - - - - - These are the possible line break classifications. - -Since new unicode versions may add new types here, applications should be ready -to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN. - -See [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/). - - - Mandatory Break (BK) - - - Carriage Return (CR) - - - Line Feed (LF) - - - Attached Characters and Combining Marks (CM) - - - Surrogates (SG) - - - Zero Width Space (ZW) - - - Inseparable (IN) - - - Non-breaking ("Glue") (GL) - - - Contingent Break Opportunity (CB) - - - Space (SP) - - - Break Opportunity After (BA) - - - Break Opportunity Before (BB) - - - Break Opportunity Before and After (B2) - - - Hyphen (HY) - - - Nonstarter (NS) - - - Opening Punctuation (OP) - - - Closing Punctuation (CL) - - - Ambiguous Quotation (QU) - - - Exclamation/Interrogation (EX) - - - Ideographic (ID) - - - Numeric (NU) - - - Infix Separator (Numeric) (IS) - - - Symbols Allowing Break After (SY) - - - Ordinary Alphabetic and Symbol Characters (AL) - - - Prefix (Numeric) (PR) - - - Postfix (Numeric) (PO) - - - Complex Content Dependent (South East Asian) (SA) - - - Ambiguous (Alphabetic or Ideographic) (AI) - - - Unknown (XX) - - - Next Line (NL) - - - Word Joiner (WJ) - - - Hangul L Jamo (JL) - - - Hangul V Jamo (JV) - - - Hangul T Jamo (JT) - - - Hangul LV Syllable (H2) - - - Hangul LVT Syllable (H3) - - - Closing Parenthesis (CP). Since 2.28 - - - Conditional Japanese Starter (CJ). Since: 2.32 - - - Hebrew Letter (HL). Since: 2.32 - - - Regional Indicator (RI). Since: 2.36 - - - Emoji Base (EB). Since: 2.50 - - - Emoji Modifier (EM). Since: 2.50 - - - Zero Width Joiner (ZWJ). Since: 2.50 - - - - The #GUnicodeScript enumeration identifies different writing -systems. The values correspond to the names as defined in the -Unicode standard. The enumeration has been added in GLib 2.14, -and is interchangeable with #PangoScript. - -Note that new types may be added in the future. Applications -should be ready to handle unknown values. -See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/). - - - a value never returned from g_unichar_get_script() - - - a character used by multiple different scripts - - - a mark glyph that takes its script from the - base glyph to which it is attached - - - Arabic - - - Armenian - - - Bengali - - - Bopomofo - - - Cherokee - - - Coptic - - - Cyrillic - - - Deseret - - - Devanagari - - - Ethiopic - - - Georgian - - - Gothic - - - Greek - - - Gujarati - - - Gurmukhi - - - Han - - - Hangul - - - Hebrew - - - Hiragana - - - Kannada - - - Katakana - - - Khmer - - - Lao - - - Latin - - - Malayalam - - - Mongolian - - - Myanmar - - - Ogham - - - Old Italic - - - Oriya - - - Runic - - - Sinhala - - - Syriac - - - Tamil - - - Telugu - - - Thaana - - - Thai - - - Tibetan - - - Canadian Aboriginal - - - Yi - - - Tagalog - - - Hanunoo - - - Buhid - - - Tagbanwa - - - Braille - - - Cypriot - - - Limbu - - - Osmanya - - - Shavian - - - Linear B - - - Tai Le - - - Ugaritic - - - New Tai Lue - - - Buginese - - - Glagolitic - - - Tifinagh - - - Syloti Nagri - - - Old Persian - - - Kharoshthi - - - an unassigned code point - - - Balinese - - - Cuneiform - - - Phoenician - - - Phags-pa - - - N'Ko - - - Kayah Li. Since 2.16.3 - - - Lepcha. Since 2.16.3 - - - Rejang. Since 2.16.3 - - - Sundanese. Since 2.16.3 - - - Saurashtra. Since 2.16.3 - - - Cham. Since 2.16.3 - - - Ol Chiki. Since 2.16.3 - - - Vai. Since 2.16.3 - - - Carian. Since 2.16.3 - - - Lycian. Since 2.16.3 - - - Lydian. Since 2.16.3 - - - Avestan. Since 2.26 - - - Bamum. Since 2.26 - - - Egyptian Hieroglpyhs. Since 2.26 - - - Imperial Aramaic. Since 2.26 - - - Inscriptional Pahlavi. Since 2.26 - - - Inscriptional Parthian. Since 2.26 - - - Javanese. Since 2.26 - - - Kaithi. Since 2.26 - - - Lisu. Since 2.26 - - - Meetei Mayek. Since 2.26 - - - Old South Arabian. Since 2.26 - - - Old Turkic. Since 2.28 - - - Samaritan. Since 2.26 - - - Tai Tham. Since 2.26 - - - Tai Viet. Since 2.26 - - - Batak. Since 2.28 - - - Brahmi. Since 2.28 - - - Mandaic. Since 2.28 - - - Chakma. Since: 2.32 - - - Meroitic Cursive. Since: 2.32 - - - Meroitic Hieroglyphs. Since: 2.32 - - - Miao. Since: 2.32 - - - Sharada. Since: 2.32 - - - Sora Sompeng. Since: 2.32 - - - Takri. Since: 2.32 - - - Bassa. Since: 2.42 - - - Caucasian Albanian. Since: 2.42 - - - Duployan. Since: 2.42 - - - Elbasan. Since: 2.42 - - - Grantha. Since: 2.42 - - - Kjohki. Since: 2.42 - - - Khudawadi, Sindhi. Since: 2.42 - - - Linear A. Since: 2.42 - - - Mahajani. Since: 2.42 - - - Manichaean. Since: 2.42 - - - Mende Kikakui. Since: 2.42 - - - Modi. Since: 2.42 - - - Mro. Since: 2.42 - - - Nabataean. Since: 2.42 - - - Old North Arabian. Since: 2.42 - - - Old Permic. Since: 2.42 - - - Pahawh Hmong. Since: 2.42 - - - Palmyrene. Since: 2.42 - - - Pau Cin Hau. Since: 2.42 - - - Psalter Pahlavi. Since: 2.42 - - - Siddham. Since: 2.42 - - - Tirhuta. Since: 2.42 - - - Warang Citi. Since: 2.42 - - - Ahom. Since: 2.48 - - - Anatolian Hieroglyphs. Since: 2.48 - - - Hatran. Since: 2.48 - - - Multani. Since: 2.48 - - - Old Hungarian. Since: 2.48 - - - Signwriting. Since: 2.48 - - - Adlam. Since: 2.50 - - - Bhaiksuki. Since: 2.50 - - - Marchen. Since: 2.50 - - - Newa. Since: 2.50 - - - Osage. Since: 2.50 - - - Tangut. Since: 2.50 - - - Masaram Gondi. Since: 2.54 - - - Nushu. Since: 2.54 - - - Soyombo. Since: 2.54 - - - Zanabazar Square. Since: 2.54 - - - Dogra. Since: 2.58 - - - Gunjala Gondi. Since: 2.58 - - - Hanifi Rohingya. Since: 2.58 - - - Makasar. Since: 2.58 - - - Medefaidrin. Since: 2.58 - - - Old Sogdian. Since: 2.58 - - - Sogdian. Since: 2.58 - - - Elym. Since: 2.62 - - - Nand. Since: 2.62 - - - Rohg. Since: 2.62 - - - Wcho. Since: 2.62 - - - - These are the possible character classifications from the -Unicode specification. -See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values). - - - General category "Other, Control" (Cc) - - - General category "Other, Format" (Cf) - - - General category "Other, Not Assigned" (Cn) - - - General category "Other, Private Use" (Co) - - - General category "Other, Surrogate" (Cs) - - - General category "Letter, Lowercase" (Ll) - - - General category "Letter, Modifier" (Lm) - - - General category "Letter, Other" (Lo) - - - General category "Letter, Titlecase" (Lt) - - - General category "Letter, Uppercase" (Lu) - - - General category "Mark, Spacing" (Mc) - - - General category "Mark, Enclosing" (Me) - - - General category "Mark, Nonspacing" (Mn) - - - General category "Number, Decimal Digit" (Nd) - - - General category "Number, Letter" (Nl) - - - General category "Number, Other" (No) - - - General category "Punctuation, Connector" (Pc) - - - General category "Punctuation, Dash" (Pd) - - - General category "Punctuation, Close" (Pe) - - - General category "Punctuation, Final quote" (Pf) - - - General category "Punctuation, Initial quote" (Pi) - - - General category "Punctuation, Other" (Po) - - - General category "Punctuation, Open" (Ps) - - - General category "Symbol, Currency" (Sc) - - - General category "Symbol, Modifier" (Sk) - - - General category "Symbol, Math" (Sm) - - - General category "Symbol, Other" (So) - - - General category "Separator, Line" (Zl) - - - General category "Separator, Paragraph" (Zp) - - - General category "Separator, Space" (Zs) - - - - The type of functions to be called when a UNIX fd watch source -triggers. - - - %FALSE if the source should be removed - - - - - the fd that triggered the event - - - - the IO conditions reported on @fd - - - - user data passed to g_unix_fd_add() - - - - - - These are logical ids for special directories which are defined -depending on the platform used. You should use g_get_user_special_dir() -to retrieve the full path associated to the logical id. - -The #GUserDirectory enumeration can be extended at later date. Not -every platform has a directory for every logical id in this -enumeration. - - - the user's Desktop directory - - - the user's Documents directory - - - the user's Downloads directory - - - the user's Music directory - - - the user's Pictures directory - - - the user's shared directory - - - the user's Templates directory - - - the user's Movies directory - - - the number of enum values - - - - A stack-allocated #GVariantBuilder must be initialized if it is -used together with g_auto() to avoid warnings or crashes if -function returns before g_variant_builder_init() is called on the -builder. This macro can be used as initializer instead of an -explicit zeroing a variable when declaring it and a following -g_variant_builder_init(), but it cannot be assigned to a variable. - -The passed @variant_type should be a static GVariantType to avoid -lifetime issues, as copying the @variant_type does not happen in -the G_VARIANT_BUILDER_INIT() call, but rather in functions that -make sure that #GVariantBuilder is valid. - -|[ - g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); -]| - - - - a const GVariantType* - - - - - A stack-allocated #GVariantDict must be initialized if it is used -together with g_auto() to avoid warnings or crashes if function -returns before g_variant_dict_init() is called on the builder. -This macro can be used as initializer instead of an explicit -zeroing a variable when declaring it and a following -g_variant_dict_init(), but it cannot be assigned to a variable. - -The passed @asv has to live long enough for #GVariantDict to gather -the entries from, as the gathering does not happen in the -G_VARIANT_DICT_INIT() call, but rather in functions that make sure -that #GVariantDict is valid. In context where the initialization -value has to be a constant expression, the only possible value of -@asv is %NULL. It is still possible to call g_variant_dict_init() -safely with a different @asv right after the variable was -initialized with G_VARIANT_DICT_INIT(). - -|[ - g_autoptr(GVariant) variant = get_asv_variant (); - g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); -]| - - - - a GVariant* - - - - - Converts a string to a const #GVariantType. Depending on the -current debugging level, this function may perform a runtime check -to ensure that @string is a valid GVariant type string. - -It is always a programmer error to use this macro with an invalid -type string. If in doubt, use g_variant_type_string_is_valid() to -check if the string is valid. - -Since 2.24 - - - - a well-formed #GVariantType type string - - - - - Portable way to copy va_list variables. - -In order to use this function, you must include string.h yourself, -because this macro may use memmove() and GLib does not include -string.h for you. - - - - the va_list variable to place a copy of @ap2 in - - - a va_list - - - - - - - - - A macro that should be defined by the user prior to including -the glib.h header. -The definition should be one of the predefined GLib version -macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... - -This macro defines the earliest version of GLib that the package is -required to be able to compile against. - -If the compiler is configured to warn about the use of deprecated -functions, then using functions that were deprecated in version -%GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but -using functions deprecated in later releases will not). - - - - - #GVariant is a variant datatype; it can contain one or more values -along with information about the type of the values. - -A #GVariant may contain simple types, like an integer, or a boolean value; -or complex types, like an array of two strings, or a dictionary of key -value pairs. A #GVariant is also immutable: once it's been created neither -its type nor its content can be modified further. - -GVariant is useful whenever data needs to be serialized, for example when -sending method parameters in DBus, or when saving settings using GSettings. - -When creating a new #GVariant, you pass the data you want to store in it -along with a string representing the type of data you wish to pass to it. - -For instance, if you want to create a #GVariant holding an integer value you -can use: - -|[<!-- language="C" --> - GVariant *v = g_variant_new ("u", 40); -]| - -The string "u" in the first argument tells #GVariant that the data passed to -the constructor (40) is going to be an unsigned integer. - -More advanced examples of #GVariant in use can be found in documentation for -[GVariant format strings][gvariant-format-strings-pointers]. - -The range of possible values is determined by the type. - -The type system used by #GVariant is #GVariantType. - -#GVariant instances always have a type and a value (which are given -at construction time). The type and value of a #GVariant instance -can never change other than by the #GVariant itself being -destroyed. A #GVariant cannot contain a pointer. - -#GVariant is reference counted using g_variant_ref() and -g_variant_unref(). #GVariant also has floating reference counts -- -see g_variant_ref_sink(). - -#GVariant is completely threadsafe. A #GVariant instance can be -concurrently accessed in any way from any number of threads without -problems. - -#GVariant is heavily optimised for dealing with data in serialised -form. It works particularly well with data located in memory-mapped -files. It can perform nearly all deserialisation operations in a -small constant time, usually touching only a single memory page. -Serialised #GVariant data can also be sent over the network. - -#GVariant is largely compatible with D-Bus. Almost all types of -#GVariant instances can be sent over D-Bus. See #GVariantType for -exceptions. (However, #GVariant's serialisation format is not the same -as the serialisation format of a D-Bus message body: use #GDBusMessage, -in the gio library, for those.) - -For space-efficiency, the #GVariant serialisation format does not -automatically include the variant's length, type or endianness, -which must either be implied from context (such as knowledge that a -particular file format always contains a little-endian -%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) -or supplied out-of-band (for instance, a length, type and/or endianness -indicator could be placed at the beginning of a file, network message -or network stream). - -A #GVariant's size is limited mainly by any lower level operating -system constraints, such as the number of bits in #gsize. For -example, it is reasonable to have a 2GB file mapped into memory -with #GMappedFile, and call g_variant_new_from_data() on it. - -For convenience to C programmers, #GVariant features powerful -varargs-based value construction and destruction. This feature is -designed to be embedded in other libraries. - -There is a Python-inspired text language for describing #GVariant -values. #GVariant includes a printer for this language and a parser -with type inferencing. - -## Memory Use - -#GVariant tries to be quite efficient with respect to memory use. -This section gives a rough idea of how much memory is used by the -current implementation. The information here is subject to change -in the future. - -The memory allocated by #GVariant can be grouped into 4 broad -purposes: memory for serialised data, memory for the type -information cache, buffer management memory and memory for the -#GVariant structure itself. - -## Serialised Data Memory - -This is the memory that is used for storing GVariant data in -serialised form. This is what would be sent over the network or -what would end up on disk, not counting any indicator of the -endianness, or of the length or type of the top-level variant. - -The amount of memory required to store a boolean is 1 byte. 16, -32 and 64 bit integers and double precision floating point numbers -use their "natural" size. Strings (including object path and -signature strings) are stored with a nul terminator, and as such -use the length of the string plus 1 byte. - -Maybe types use no space at all to represent the null value and -use the same amount of space (sometimes plus one byte) as the -equivalent non-maybe-typed value to represent the non-null case. - -Arrays use the amount of space required to store each of their -members, concatenated. Additionally, if the items stored in an -array are not of a fixed-size (ie: strings, other arrays, etc) -then an additional framing offset is stored for each item. The -size of this offset is either 1, 2 or 4 bytes depending on the -overall size of the container. Additionally, extra padding bytes -are added as required for alignment of child values. - -Tuples (including dictionary entries) use the amount of space -required to store each of their members, concatenated, plus one -framing offset (as per arrays) for each non-fixed-sized item in -the tuple, except for the last one. Additionally, extra padding -bytes are added as required for alignment of child values. - -Variants use the same amount of space as the item inside of the -variant, plus 1 byte, plus the length of the type string for the -item inside the variant. - -As an example, consider a dictionary mapping strings to variants. -In the case that the dictionary is empty, 0 bytes are required for -the serialisation. - -If we add an item "width" that maps to the int32 value of 500 then -we will use 4 byte to store the int32 (so 6 for the variant -containing it) and 6 bytes for the string. The variant must be -aligned to 8 after the 6 bytes of the string, so that's 2 extra -bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used -for the dictionary entry. An additional 1 byte is added to the -array as a framing offset making a total of 15 bytes. - -If we add another entry, "title" that maps to a nullable string -that happens to have a value of null, then we use 0 bytes for the -null value (and 3 bytes for the variant to contain it along with -its type string) plus 6 bytes for the string. Again, we need 2 -padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. - -We now require extra padding between the two items in the array. -After the 14 bytes of the first item, that's 2 bytes required. -We now require 2 framing offsets for an extra two -bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item -dictionary. - -## Type Information Cache - -For each GVariant type that currently exists in the program a type -information structure is kept in the type information cache. The -type information structure is required for rapid deserialisation. - -Continuing with the above example, if a #GVariant exists with the -type "a{sv}" then a type information struct will exist for -"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type -will share the same type information. Additionally, all -single-digit types are stored in read-only static memory and do -not contribute to the writable memory footprint of a program using -#GVariant. - -Aside from the type information structures stored in read-only -memory, there are two forms of type information. One is used for -container types where there is a single element type: arrays and -maybe types. The other is used for container types where there -are multiple element types: tuples and dictionary entries. - -Array type info structures are 6 * sizeof (void *), plus the -memory required to store the type string itself. This means that -on 32-bit systems, the cache entry for "a{sv}" would require 30 -bytes of memory (plus malloc overhead). - -Tuple type info structures are 6 * sizeof (void *), plus 4 * -sizeof (void *) for each item in the tuple, plus the memory -required to store the type string itself. A 2-item tuple, for -example, would have a type information structure that consumed -writable memory in the size of 14 * sizeof (void *) (plus type -string) This means that on 32-bit systems, the cache entry for -"{sv}" would require 61 bytes of memory (plus malloc overhead). - -This means that in total, for our "a{sv}" example, 91 bytes of -type information would be allocated. - -The type information cache, additionally, uses a #GHashTable to -store and look up the cached items and stores a pointer to this -hash table in static storage. The hash table is freed when there -are zero items in the type cache. - -Although these sizes may seem large it is important to remember -that a program will probably only have a very small number of -different types of values in it and that only one type information -structure is required for many different values of the same type. - -## Buffer Management Memory - -#GVariant uses an internal buffer management structure to deal -with the various different possible sources of serialised data -that it uses. The buffer is responsible for ensuring that the -correct call is made when the data is no longer in use by -#GVariant. This may involve a g_free() or a g_slice_free() or -even g_mapped_file_unref(). - -One buffer management structure is used for each chunk of -serialised data. The size of the buffer management structure -is 4 * (void *). On 32-bit systems, that's 16 bytes. - -## GVariant structure - -The size of a #GVariant structure is 6 * (void *). On 32-bit -systems, that's 24 bytes. - -#GVariant structures only exist if they are explicitly created -with API calls. For example, if a #GVariant is constructed out of -serialised data for the example given above (with the dictionary) -then although there are 9 individual values that comprise the -entire dictionary (two keys, two values, two variants containing -the values, two dictionary entries, plus the dictionary itself), -only 1 #GVariant instance exists -- the one referring to the -dictionary. - -If calls are made to start accessing the other values then -#GVariant instances will exist for those values only for as long -as they are in use (ie: until you call g_variant_unref()). The -type information is shared. The serialised data and the buffer -management structure for that serialised data is shared by the -child. - -## Summary - -To put the entire example together, for our dictionary mapping -strings to variants (with two entries, as given above), we are -using 91 bytes of memory for type information, 29 bytes of memory -for the serialised data, 16 bytes for buffer management and 24 -bytes for the #GVariant instance, or a total of 160 bytes, plus -malloc overhead. If we were to use g_variant_get_child_value() to -access the two dictionary entries, we would use an additional 48 -bytes. If we were to have other dictionaries of the same type, we -would use more memory for the serialised data and buffer -management for those dictionaries, but the type information would -be shared. - - - Creates a new #GVariant instance. - -Think of this function as an analogue to g_strdup_printf(). - -The type of the created instance and the arguments that are expected -by this function are determined by @format_string. See the section on -[GVariant format strings][gvariant-format-strings]. Please note that -the syntax of the format string is very likely to be extended in the -future. - -The first character of the format string must not be '*' '?' '@' or -'r'; in essence, a new #GVariant must always be constructed by this -function (and not merely passed through it unmodified). - -Note that the arguments must be of the correct width for their types -specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. - -|[<!-- language="C" --> -MyFlags some_flags = FLAG_ONE | FLAG_TWO; -const gchar *some_strings[] = { "a", "b", "c", NULL }; -GVariant *new_variant; - -new_variant = g_variant_new ("(t^as)", - // This cast is required. - (guint64) some_flags, - some_strings); -]| - - - a new floating #GVariant instance - - - - - a #GVariant format string - - - - arguments, as per @format_string - - - - - - Creates a new #GVariant array from @children. - -@child_type must be non-%NULL if @n_children is zero. Otherwise, the -child type is determined by inspecting the first element of the -@children array. If @child_type is non-%NULL then it must be a -definite type. - -The items of the array are taken from the @children array. No entry -in the @children array may be %NULL. - -All items in the array must have the same type, which must be the -same as @child_type, if given. - -If the @children are floating references (see g_variant_ref_sink()), the -new instance takes ownership of them as if via g_variant_ref_sink(). - - - a floating reference to a new #GVariant array - - - - - the element type of the new array - - - - an array of - #GVariant pointers, the children - - - - - - the length of @children - - - - - - Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. - - - a floating reference to a new boolean #GVariant instance - - - - - a #gboolean value - - - - - - Creates a new byte #GVariant instance. - - - a floating reference to a new byte #GVariant instance - - - - - a #guint8 value - - - - - - Creates an array-of-bytes #GVariant with the contents of @string. -This function is just like g_variant_new_string() except that the -string need not be valid UTF-8. - -The nul terminator character at the end of the string is stored in -the array. - - - a floating reference to a new bytestring #GVariant instance - - - - - a normal - nul-terminated string in no particular encoding - - - - - - - - Constructs an array of bytestring #GVariant from the given array of -strings. - -If @length is -1 then @strv is %NULL-terminated. - - - a new floating #GVariant instance - - - - - an array of strings - - - - - - the length of @strv, or -1 - - - - - - Creates a new dictionary entry #GVariant. @key and @value must be -non-%NULL. @key must be a value of a basic type (ie: not a container). - -If the @key or @value are floating references (see g_variant_ref_sink()), -the new instance takes ownership of them as if via g_variant_ref_sink(). - - - a floating reference to a new dictionary entry #GVariant - - - - - a basic #GVariant, the key - - - - a #GVariant, the value - - - - - - Creates a new double #GVariant instance. - - - a floating reference to a new double #GVariant instance - - - - - a #gdouble floating point value - - - - - - Constructs a new array #GVariant instance, where the elements are -of @element_type type. - -@elements must be an array with fixed-sized elements. Numeric types are -fixed-size as are tuples containing only other fixed-sized types. - -@element_size must be the size of a single element in the array. -For example, if calling this function for an array of 32-bit integers, -you might say sizeof(gint32). This value isn't used except for the purpose -of a double-check that the form of the serialised data matches the caller's -expectation. - -@n_elements must be the length of the @elements array. - - - a floating reference to a new array #GVariant instance - - - - - the #GVariantType of each element - - - - a pointer to the fixed array of contiguous elements - - - - the number of elements - - - - the size of each element - - - - - - Constructs a new serialised-mode #GVariant instance. This is the -inner interface for creation of new serialised values that gets -called from various functions in gvariant.c. - -A reference is taken on @bytes. - -The data in @bytes must be aligned appropriately for the @type being loaded. -Otherwise this function will internally create a copy of the memory (since -GLib 2.60) or (in older versions) fail and exit the process. - - - a new #GVariant with a floating reference - - - - - a #GVariantType - - - - a #GBytes - - - - if the contents of @bytes are trusted - - - - - - Creates a new #GVariant instance from serialised data. - -@type is the type of #GVariant instance that will be constructed. -The interpretation of @data depends on knowing the type. - -@data is not modified by this function and must remain valid with an -unchanging value until such a time as @notify is called with -@user_data. If the contents of @data change before that time then -the result is undefined. - -If @data is trusted to be serialised data in normal form then -@trusted should be %TRUE. This applies to serialised data created -within this process or read from a trusted location on the disk (such -as a file installed in /usr/lib alongside your application). You -should set trusted to %FALSE if @data is read from the network, a -file in the user's home directory, etc. - -If @data was not stored in this machine's native endianness, any multi-byte -numeric values in the returned variant will also be in non-native -endianness. g_variant_byteswap() can be used to recover the original values. - -@notify will be called with @user_data when @data is no longer -needed. The exact time of this call is unspecified and might even be -before this function returns. - -Note: @data must be backed by memory that is aligned appropriately for the -@type being loaded. Otherwise this function will internally create a copy of -the memory (since GLib 2.60) or (in older versions) fail and exit the -process. - - - a new floating #GVariant of type @type - - - - - a definite #GVariantType - - - - the serialised data - - - - - - the size of @data - - - - %TRUE if @data is definitely in normal form - - - - function to call when @data is no longer needed - - - - data for @notify - - - - - - Creates a new handle #GVariant instance. - -By convention, handles are indexes into an array of file descriptors -that are sent alongside a D-Bus message. If you're not interacting -with D-Bus, you probably don't need them. - - - a floating reference to a new handle #GVariant instance - - - - - a #gint32 value - - - - - - Creates a new int16 #GVariant instance. - - - a floating reference to a new int16 #GVariant instance - - - - - a #gint16 value - - - - - - Creates a new int32 #GVariant instance. - - - a floating reference to a new int32 #GVariant instance - - - - - a #gint32 value - - - - - - Creates a new int64 #GVariant instance. - - - a floating reference to a new int64 #GVariant instance - - - - - a #gint64 value - - - - - - Depending on if @child is %NULL, either wraps @child inside of a -maybe container or creates a Nothing instance for the given @type. - -At least one of @child_type and @child must be non-%NULL. -If @child_type is non-%NULL then it must be a definite type. -If they are both non-%NULL then @child_type must be the type -of @child. - -If @child is a floating reference (see g_variant_ref_sink()), the new -instance takes ownership of @child. - - - a floating reference to a new #GVariant maybe instance - - - - - the #GVariantType of the child, or %NULL - - - - the child value, or %NULL - - - - - - Creates a D-Bus object path #GVariant with the contents of @string. -@string must be a valid D-Bus object path. Use -g_variant_is_object_path() if you're not sure. - - - a floating reference to a new object path #GVariant instance - - - - - a normal C nul-terminated string - - - - - - Constructs an array of object paths #GVariant from the given array of -strings. - -Each string must be a valid #GVariant object path; see -g_variant_is_object_path(). - -If @length is -1 then @strv is %NULL-terminated. - - - a new floating #GVariant instance - - - - - an array of strings - - - - - - the length of @strv, or -1 - - - - - - Parses @format and returns the result. - -@format must be a text format #GVariant with one extension: at any -point that a value may appear in the text, a '%' character followed -by a GVariant format string (as per g_variant_new()) may appear. In -that case, the same arguments are collected from the argument list as -g_variant_new() would have collected. - -Note that the arguments must be of the correct width for their types -specified in @format. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. - -Consider this simple example: -|[<!-- language="C" --> - g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); -]| - -In the example, the variable argument parameters are collected and -filled in as if they were part of the original string to produce the -result of -|[<!-- language="C" --> -[('one', 1), ('two', 2), ('three', 3)] -]| - -This function is intended only to be used with @format as a string -literal. Any parse error is fatal to the calling process. If you -want to parse data from untrusted sources, use g_variant_parse(). - -You may not use this function to return, unmodified, a single -#GVariant pointer from the argument list. ie: @format may not solely -be anything along the lines of "%*", "%?", "\%r", or anything starting -with "%@". - - - a new floating #GVariant instance - - - - - a text format #GVariant - - - - arguments as per @format - - - - - - Parses @format and returns the result. - -This is the version of g_variant_new_parsed() intended to be used -from libraries. - -The return value will be floating if it was a newly created GVariant -instance. In the case that @format simply specified the collection -of a #GVariant pointer (eg: @format was "%*") then the collected -#GVariant pointer will be returned unmodified, without adding any -additional references. - -Note that the arguments in @app must be of the correct width for their types -specified in @format when collected into the #va_list. See -the [GVariant varargs documentation][gvariant-varargs]. - -In order to behave correctly in all cases it is necessary for the -calling function to g_variant_ref_sink() the return result before -returning control to the user that originally provided the pointer. -At this point, the caller will have their own full reference to the -result. This can also be done by adding the result to a container, -or by passing it to another g_variant_new() call. - - - a new, usually floating, #GVariant - - - - - a text format #GVariant - - - - a pointer to a #va_list - - - - - - Creates a string-type GVariant using printf formatting. - -This is similar to calling g_strdup_printf() and then -g_variant_new_string() but it saves a temporary variable and an -unnecessary copy. - - - a floating reference to a new string - #GVariant instance - - - - - a printf-style format string - - - - arguments for @format_string - - - - - - Creates a D-Bus type signature #GVariant with the contents of -@string. @string must be a valid D-Bus type signature. Use -g_variant_is_signature() if you're not sure. - - - a floating reference to a new signature #GVariant instance - - - - - a normal C nul-terminated string - - - - - - Creates a string #GVariant with the contents of @string. - -@string must be valid UTF-8, and must not be %NULL. To encode -potentially-%NULL strings, use g_variant_new() with `ms` as the -[format string][gvariant-format-strings-maybe-types]. - - - a floating reference to a new string #GVariant instance - - - - - a normal UTF-8 nul-terminated string - - - - - - Constructs an array of strings #GVariant from the given array of -strings. - -If @length is -1 then @strv is %NULL-terminated. - - - a new floating #GVariant instance - - - - - an array of strings - - - - - - the length of @strv, or -1 - - - - - - Creates a string #GVariant with the contents of @string. - -@string must be valid UTF-8, and must not be %NULL. To encode -potentially-%NULL strings, use this with g_variant_new_maybe(). - -This function consumes @string. g_free() will be called on @string -when it is no longer required. - -You must not modify or access @string in any other way after passing -it to this function. It is even possible that @string is immediately -freed. - - - a floating reference to a new string - #GVariant instance - - - - - a normal UTF-8 nul-terminated string - - - - - - Creates a new tuple #GVariant out of the items in @children. The -type is determined from the types of @children. No entry in the -@children array may be %NULL. - -If @n_children is 0 then the unit tuple is constructed. - -If the @children are floating references (see g_variant_ref_sink()), the -new instance takes ownership of them as if via g_variant_ref_sink(). - - - a floating reference to a new #GVariant tuple - - - - - the items to make the tuple out of - - - - - - the length of @children - - - - - - Creates a new uint16 #GVariant instance. - - - a floating reference to a new uint16 #GVariant instance - - - - - a #guint16 value - - - - - - Creates a new uint32 #GVariant instance. - - - a floating reference to a new uint32 #GVariant instance - - - - - a #guint32 value - - - - - - Creates a new uint64 #GVariant instance. - - - a floating reference to a new uint64 #GVariant instance - - - - - a #guint64 value - - - - - - This function is intended to be used by libraries based on -#GVariant that want to provide g_variant_new()-like functionality -to their users. - -The API is more general than g_variant_new() to allow a wider range -of possible uses. - -@format_string must still point to a valid format string, but it only -needs to be nul-terminated if @endptr is %NULL. If @endptr is -non-%NULL then it is updated to point to the first character past the -end of the format string. - -@app is a pointer to a #va_list. The arguments, according to -@format_string, are collected from this #va_list and the list is left -pointing to the argument following the last. - -Note that the arguments in @app must be of the correct width for their -types specified in @format_string when collected into the #va_list. -See the [GVariant varargs documentation][gvariant-varargs]. - -These two generalisations allow mixing of multiple calls to -g_variant_new_va() and g_variant_get_va() within a single actual -varargs call by the user. - -The return value will be floating if it was a newly created GVariant -instance (for example, if the format string was "(ii)"). In the case -that the format_string was '*', '?', 'r', or a format starting with -'@' then the collected #GVariant pointer will be returned unmodified, -without adding any additional references. - -In order to behave correctly in all cases it is necessary for the -calling function to g_variant_ref_sink() the return result before -returning control to the user that originally provided the pointer. -At this point, the caller will have their own full reference to the -result. This can also be done by adding the result to a container, -or by passing it to another g_variant_new() call. - - - a new, usually floating, #GVariant - - - - - a string that is prefixed with a format string - - - - location to store the end pointer, - or %NULL - - - - a pointer to a #va_list - - - - - - Boxes @value. The result is a #GVariant instance representing a -variant containing the original value. - -If @child is a floating reference (see g_variant_ref_sink()), the new -instance takes ownership of @child. - - - a floating reference to a new variant #GVariant instance - - - - - a #GVariant instance - - - - - - Performs a byteswapping operation on the contents of @value. The -result is that all multi-byte numeric data contained in @value is -byteswapped. That includes 16, 32, and 64bit signed and unsigned -integers as well as file handles and double precision floating point -values. - -This function is an identity mapping on any value that does not -contain multi-byte numeric data. That include strings, booleans, -bytes and containers containing only these things (recursively). - -The returned value is always in normal form and is marked as trusted. - - - the byteswapped form of @value - - - - - a #GVariant - - - - - - Checks if calling g_variant_get() with @format_string on @value would -be valid from a type-compatibility standpoint. @format_string is -assumed to be a valid format string (from a syntactic standpoint). - -If @copy_only is %TRUE then this function additionally checks that it -would be safe to call g_variant_unref() on @value immediately after -the call to g_variant_get() without invalidating the result. This is -only possible if deep copies are made (ie: there are no pointers to -the data inside of the soon-to-be-freed #GVariant instance). If this -check fails then a g_critical() is printed and %FALSE is returned. - -This function is meant to be used by functions that wish to provide -varargs accessors to #GVariant values of uncertain values (eg: -g_variant_lookup() or g_menu_model_get_item_attribute()). - - - %TRUE if @format_string is safe to use - - - - - a #GVariant - - - - a valid #GVariant format string - - - - %TRUE to ensure the format string makes deep copies - - - - - - Classifies @value according to its top-level type. - - - the #GVariantClass of @value - - - - - a #GVariant - - - - - - Compares @one and @two. - -The types of @one and @two are #gconstpointer only to allow use of -this function with #GTree, #GPtrArray, etc. They must each be a -#GVariant. - -Comparison is only defined for basic types (ie: booleans, numbers, -strings). For booleans, %FALSE is less than %TRUE. Numbers are -ordered in the usual way. Strings are in ASCII lexographical order. - -It is a programmer error to attempt to compare container values or -two values that have types that are not exactly equal. For example, -you cannot compare a 32-bit signed integer with a 32-bit unsigned -integer. Also note that this function is not particularly -well-behaved when it comes to comparison of doubles; in particular, -the handling of incomparable values (ie: NaN) is undefined. - -If you only require an equality comparison, g_variant_equal() is more -general. - - - negative value if a < b; - zero if a = b; - positive value if a > b. - - - - - a basic-typed #GVariant instance - - - - a #GVariant instance of the same type - - - - - - Similar to g_variant_get_bytestring() except that instead of -returning a constant string, the string is duplicated. - -The return value must be freed using g_free(). - - - - a newly allocated string - - - - - - - an array-of-bytes #GVariant instance - - - - a pointer to a #gsize, to store - the length (not including the nul terminator) - - - - - - Gets the contents of an array of array of bytes #GVariant. This call -makes a deep copy; the return result should be released with -g_strfreev(). - -If @length is non-%NULL then the number of elements in the result is -stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of strings - - - - - - - an array of array of bytes #GVariant ('aay') - - - - the length of the result, or %NULL - - - - - - Gets the contents of an array of object paths #GVariant. This call -makes a deep copy; the return result should be released with -g_strfreev(). - -If @length is non-%NULL then the number of elements in the result -is stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of strings - - - - - - - an array of object paths #GVariant - - - - the length of the result, or %NULL - - - - - - Similar to g_variant_get_string() except that instead of returning -a constant string, the string is duplicated. - -The string will always be UTF-8 encoded. - -The return value must be freed using g_free(). - - - a newly allocated string, UTF-8 encoded - - - - - a string #GVariant instance - - - - a pointer to a #gsize, to store the length - - - - - - Gets the contents of an array of strings #GVariant. This call -makes a deep copy; the return result should be released with -g_strfreev(). - -If @length is non-%NULL then the number of elements in the result -is stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of strings - - - - - - - an array of strings #GVariant - - - - the length of the result, or %NULL - - - - - - Checks if @one and @two have the same type and value. - -The types of @one and @two are #gconstpointer only to allow use of -this function with #GHashTable. They must each be a #GVariant. - - - %TRUE if @one and @two are equal - - - - - a #GVariant instance - - - - a #GVariant instance - - - - - - Deconstructs a #GVariant instance. - -Think of this function as an analogue to scanf(). - -The arguments that are expected by this function are entirely -determined by @format_string. @format_string also restricts the -permissible types of @value. It is an error to give a value with -an incompatible type. See the section on -[GVariant format strings][gvariant-format-strings]. -Please note that the syntax of the format string is very likely to be -extended in the future. - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed, -see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - - - - - - - a #GVariant instance - - - - a #GVariant format string - - - - arguments, as per @format_string - - - - - - Returns the boolean value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_BOOLEAN. - - - %TRUE or %FALSE - - - - - a boolean #GVariant instance - - - - - - Returns the byte value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_BYTE. - - - a #guint8 - - - - - a byte #GVariant instance - - - - - - Returns the string value of a #GVariant instance with an -array-of-bytes type. The string has no particular encoding. - -If the array does not end with a nul terminator character, the empty -string is returned. For this reason, you can always trust that a -non-%NULL nul-terminated string will be returned by this function. - -If the array contains a nul terminator character somewhere other than -the last byte then the returned string is the string, up to the first -such nul character. - -g_variant_get_fixed_array() should be used instead if the array contains -arbitrary data that could not be nul-terminated or could contain nul bytes. - -It is an error to call this function with a @value that is not an -array of bytes. - -The return value remains valid as long as @value exists. - - - - the constant string - - - - - - - an array-of-bytes #GVariant instance - - - - - - Gets the contents of an array of array of bytes #GVariant. This call -makes a shallow copy; the return result should be released with -g_free(), but the individual strings must not be modified. - -If @length is non-%NULL then the number of elements in the result is -stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of constant strings - - - - - - - an array of array of bytes #GVariant ('aay') - - - - the length of the result, or %NULL - - - - - - Reads a child item out of a container #GVariant instance and -deconstructs it according to @format_string. This call is -essentially a combination of g_variant_get_child_value() and -g_variant_get(). - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed, -see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - - - - - - - a container #GVariant - - - - the index of the child to deconstruct - - - - a #GVariant format string - - - - arguments, as per @format_string - - - - - - Reads a child item out of a container #GVariant instance. This -includes variants, maybes, arrays, tuples and dictionary -entries. It is an error to call this function on any other type of -#GVariant. - -It is an error if @index_ is greater than the number of child items -in the container. See g_variant_n_children(). - -The returned value is never floating. You should free it with -g_variant_unref() when you're done with it. - -There may be implementation specific restrictions on deeply nested values, -which would result in the unit tuple being returned as the child value, -instead of further nested children. #GVariant is guaranteed to handle -nesting up to at least 64 levels. - -This function is O(1). - - - the child at the specified index - - - - - a container #GVariant - - - - the index of the child to fetch - - - - - - Returns a pointer to the serialised form of a #GVariant instance. -The returned data may not be in fully-normalised form if read from an -untrusted source. The returned data must not be freed; it remains -valid for as long as @value exists. - -If @value is a fixed-sized value that was deserialised from a -corrupted serialised container then %NULL may be returned. In this -case, the proper thing to do is typically to use the appropriate -number of nul bytes in place of @value. If @value is not fixed-sized -then %NULL is never returned. - -In the case that @value is already in serialised form, this function -is O(1). If the value is not already in serialised form, -serialisation occurs implicitly and is approximately O(n) in the size -of the result. - -To deserialise the data returned by this function, in addition to the -serialised data, you must know the type of the #GVariant, and (if the -machine might be different) the endianness of the machine that stored -it. As a result, file formats or network messages that incorporate -serialised #GVariants must include this information either -implicitly (for instance "the file always contains a -%G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or -explicitly (by storing the type and/or endianness in addition to the -serialised data). - - - the serialised form of @value, or %NULL - - - - - a #GVariant instance - - - - - - Returns a pointer to the serialised form of a #GVariant instance. -The semantics of this function are exactly the same as -g_variant_get_data(), except that the returned #GBytes holds -a reference to the variant data. - - - A new #GBytes representing the variant data - - - - - a #GVariant - - - - - - Returns the double precision floating point value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_DOUBLE. - - - a #gdouble - - - - - a double #GVariant instance - - - - - - Provides access to the serialised data for an array of fixed-sized -items. - -@value must be an array with fixed-sized elements. Numeric types are -fixed-size, as are tuples containing only other fixed-sized types. - -@element_size must be the size of a single element in the array, -as given by the section on -[serialized data memory][gvariant-serialised-data-memory]. - -In particular, arrays of these fixed-sized types can be interpreted -as an array of the given C type, with @element_size set to the size -the appropriate type: -- %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) -- %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) -- %G_VARIANT_TYPE_BYTE: #guint8 -- %G_VARIANT_TYPE_HANDLE: #guint32 -- %G_VARIANT_TYPE_DOUBLE: #gdouble - -For example, if calling this function for an array of 32-bit integers, -you might say `sizeof(gint32)`. This value isn't used except for the purpose -of a double-check that the form of the serialised data matches the caller's -expectation. - -@n_elements, which must be non-%NULL, is set equal to the number of -items in the array. - - - a pointer to - the fixed array - - - - - - - a #GVariant array with fixed-sized elements - - - - a pointer to the location to store the number of items - - - - the size of each element - - - - - - Returns the 32-bit signed integer value of @value. - -It is an error to call this function with a @value of any type other -than %G_VARIANT_TYPE_HANDLE. - -By convention, handles are indexes into an array of file descriptors -that are sent alongside a D-Bus message. If you're not interacting -with D-Bus, you probably don't need them. - - - a #gint32 - - - - - a handle #GVariant instance - - - - - - Returns the 16-bit signed integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_INT16. - - - a #gint16 - - - - - an int16 #GVariant instance - - - - - - Returns the 32-bit signed integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_INT32. - - - a #gint32 - - - - - an int32 #GVariant instance - - - - - - Returns the 64-bit signed integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_INT64. - - - a #gint64 - - - - - an int64 #GVariant instance - - - - - - Given a maybe-typed #GVariant instance, extract its value. If the -value is Nothing, then this function returns %NULL. - - - the contents of @value, or %NULL - - - - - a maybe-typed value - - - - - - Gets a #GVariant instance that has the same value as @value and is -trusted to be in normal form. - -If @value is already trusted to be in normal form then a new -reference to @value is returned. - -If @value is not already trusted, then it is scanned to check if it -is in normal form. If it is found to be in normal form then it is -marked as trusted and a new reference to it is returned. - -If @value is found not to be in normal form then a new trusted -#GVariant is created with the same value as @value. - -It makes sense to call this function if you've received #GVariant -data from untrusted sources and you want to ensure your serialised -output is definitely in normal form. - -If @value is already in normal form, a new reference will be returned -(which will be floating if @value is floating). If it is not in normal form, -the newly created #GVariant will be returned with a single non-floating -reference. Typically, g_variant_take_ref() should be called on the return -value from this function to guarantee ownership of a single non-floating -reference to it. - - - a trusted #GVariant - - - - - a #GVariant - - - - - - Gets the contents of an array of object paths #GVariant. This call -makes a shallow copy; the return result should be released with -g_free(), but the individual strings must not be modified. - -If @length is non-%NULL then the number of elements in the result -is stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of constant strings - - - - - - - an array of object paths #GVariant - - - - the length of the result, or %NULL - - - - - - Determines the number of bytes that would be required to store @value -with g_variant_store(). - -If @value has a fixed-sized type then this function always returned -that fixed size. - -In the case that @value is already in serialised form or the size has -already been calculated (ie: this function has been called before) -then this function is O(1). Otherwise, the size is calculated, an -operation which is approximately O(n) in the number of values -involved. - - - the serialised size of @value - - - - - a #GVariant instance - - - - - - Returns the string value of a #GVariant instance with a string -type. This includes the types %G_VARIANT_TYPE_STRING, -%G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. - -The string will always be UTF-8 encoded, and will never be %NULL. - -If @length is non-%NULL then the length of the string (in bytes) is -returned there. For trusted values, this information is already -known. For untrusted values, a strlen() will be performed. - -It is an error to call this function with a @value of any type -other than those three. - -The return value remains valid as long as @value exists. - - - the constant string, UTF-8 encoded - - - - - a string #GVariant instance - - - - a pointer to a #gsize, - to store the length - - - - - - Gets the contents of an array of strings #GVariant. This call -makes a shallow copy; the return result should be released with -g_free(), but the individual strings must not be modified. - -If @length is non-%NULL then the number of elements in the result -is stored there. In any case, the resulting array will be -%NULL-terminated. - -For an empty array, @length will be set to 0 and a pointer to a -%NULL pointer will be returned. - - - an array of constant strings - - - - - - - an array of strings #GVariant - - - - the length of the result, or %NULL - - - - - - Determines the type of @value. - -The return value is valid for the lifetime of @value and must not -be freed. - - - a #GVariantType - - - - - a #GVariant - - - - - - Returns the type string of @value. Unlike the result of calling -g_variant_type_peek_string(), this string is nul-terminated. This -string belongs to #GVariant and must not be freed. - - - the type string for the type of @value - - - - - a #GVariant - - - - - - Returns the 16-bit unsigned integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_UINT16. - - - a #guint16 - - - - - a uint16 #GVariant instance - - - - - - Returns the 32-bit unsigned integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_UINT32. - - - a #guint32 - - - - - a uint32 #GVariant instance - - - - - - Returns the 64-bit unsigned integer value of @value. - -It is an error to call this function with a @value of any type -other than %G_VARIANT_TYPE_UINT64. - - - a #guint64 - - - - - a uint64 #GVariant instance - - - - - - This function is intended to be used by libraries based on #GVariant -that want to provide g_variant_get()-like functionality to their -users. - -The API is more general than g_variant_get() to allow a wider range -of possible uses. - -@format_string must still point to a valid format string, but it only -need to be nul-terminated if @endptr is %NULL. If @endptr is -non-%NULL then it is updated to point to the first character past the -end of the format string. - -@app is a pointer to a #va_list. The arguments, according to -@format_string, are collected from this #va_list and the list is left -pointing to the argument following the last. - -These two generalisations allow mixing of multiple calls to -g_variant_new_va() and g_variant_get_va() within a single actual -varargs call by the user. - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed, -see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - - - - - - - a #GVariant - - - - a string that is prefixed with a format string - - - - location to store the end pointer, - or %NULL - - - - a pointer to a #va_list - - - - - - Unboxes @value. The result is the #GVariant instance that was -contained in @value. - - - the item contained in the variant - - - - - a variant #GVariant instance - - - - - - Generates a hash value for a #GVariant instance. - -The output of this function is guaranteed to be the same for a given -value only per-process. It may change between different processor -architectures or even different versions of GLib. Do not use this -function as a basis for building protocols or file formats. - -The type of @value is #gconstpointer only to allow use of this -function with #GHashTable. @value must be a #GVariant. - - - a hash value corresponding to @value - - - - - a basic #GVariant value as a #gconstpointer - - - - - - Checks if @value is a container. - - - %TRUE if @value is a container - - - - - a #GVariant instance - - - - - - Checks whether @value has a floating reference count. - -This function should only ever be used to assert that a given variant -is or is not floating, or for debug purposes. To acquire a reference -to a variant that might be floating, always use g_variant_ref_sink() -or g_variant_take_ref(). - -See g_variant_ref_sink() for more information about floating reference -counts. - - - whether @value is floating - - - - - a #GVariant - - - - - - Checks if @value is in normal form. - -The main reason to do this is to detect if a given chunk of -serialised data is in normal form: load the data into a #GVariant -using g_variant_new_from_data() and then use this function to -check. - -If @value is found to be in normal form then it will be marked as -being trusted. If the value was already marked as being trusted then -this function will immediately return %TRUE. - -There may be implementation specific restrictions on deeply nested values. -GVariant is guaranteed to handle nesting up to at least 64 levels. - - - %TRUE if @value is in normal form - - - - - a #GVariant instance - - - - - - Checks if a value has a type matching the provided type. - - - %TRUE if the type of @value matches @type - - - - - a #GVariant instance - - - - a #GVariantType - - - - - - Creates a heap-allocated #GVariantIter for iterating over the items -in @value. - -Use g_variant_iter_free() to free the return value when you no longer -need it. - -A reference is taken to @value and will be released only when -g_variant_iter_free() is called. - - - a new heap-allocated #GVariantIter - - - - - a container #GVariant - - - - - - Looks up a value in a dictionary #GVariant. - -This function is a wrapper around g_variant_lookup_value() and -g_variant_get(). In the case that %NULL would have been returned, -this function returns %FALSE. Otherwise, it unpacks the returned -value and returns %TRUE. - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed, -see the section on -[GVariant format strings][gvariant-format-strings-pointers]. - -This function is currently implemented with a linear scan. If you -plan to do many lookups then #GVariantDict may be more efficient. - - - %TRUE if a value was unpacked - - - - - a dictionary #GVariant - - - - the key to look up in the dictionary - - - - a GVariant format string - - - - the arguments to unpack the value into - - - - - - Looks up a value in a dictionary #GVariant. - -This function works with dictionaries of the type a{s*} (and equally -well with type a{o*}, but we only further discuss the string case -for sake of clarity). - -In the event that @dictionary has the type a{sv}, the @expected_type -string specifies what type of value is expected to be inside of the -variant. If the value inside the variant has a different type then -%NULL is returned. In the event that @dictionary has a value type other -than v then @expected_type must directly match the value type and it is -used to unpack the value directly or an error occurs. - -In either case, if @key is not found in @dictionary, %NULL is returned. - -If the key is found and the value has the correct type, it is -returned. If @expected_type was specified then any non-%NULL return -value will have this type. - -This function is currently implemented with a linear scan. If you -plan to do many lookups then #GVariantDict may be more efficient. - - - the value of the dictionary key, or %NULL - - - - - a dictionary #GVariant - - - - the key to look up in the dictionary - - - - a #GVariantType, or %NULL - - - - - - Determines the number of children in a container #GVariant instance. -This includes variants, maybes, arrays, tuples and dictionary -entries. It is an error to call this function on any other type of -#GVariant. - -For variants, the return value is always 1. For values with maybe -types, it is always zero or one. For arrays, it is the length of the -array. For tuples it is the number of tuple items (which depends -only on the type). For dictionary entries, it is always 2 - -This function is O(1). - - - the number of children in the container - - - - - a container #GVariant - - - - - - Pretty-prints @value in the format understood by g_variant_parse(). - -The format is described [here][gvariant-text]. - -If @type_annotate is %TRUE, then type information is included in -the output. - - - a newly-allocated string holding the result. - - - - - a #GVariant - - - - %TRUE if type information should be included in - the output - - - - - - Behaves as g_variant_print(), but operates on a #GString. - -If @string is non-%NULL then it is appended to and returned. Else, -a new empty #GString is allocated and it is returned. - - - a #GString containing the string - - - - - a #GVariant - - - - a #GString, or %NULL - - - - %TRUE if type information should be included in - the output - - - - - - Increases the reference count of @value. - - - the same @value - - - - - a #GVariant - - - - - - #GVariant uses a floating reference count system. All functions with -names starting with `g_variant_new_` return floating -references. - -Calling g_variant_ref_sink() on a #GVariant with a floating reference -will convert the floating reference into a full reference. Calling -g_variant_ref_sink() on a non-floating #GVariant results in an -additional normal reference being added. - -In other words, if the @value is floating, then this call "assumes -ownership" of the floating reference, converting it to a normal -reference. If the @value is not floating, then this call adds a -new normal reference increasing the reference count by one. - -All calls that result in a #GVariant instance being inserted into a -container will call g_variant_ref_sink() on the instance. This means -that if the value was just created (and has only its floating -reference) then the container will assume sole ownership of the value -at that point and the caller will not need to unreference it. This -makes certain common styles of programming much easier while still -maintaining normal refcounting semantics in situations where values -are not floating. - - - the same @value - - - - - a #GVariant - - - - - - Stores the serialised form of @value at @data. @data should be -large enough. See g_variant_get_size(). - -The stored data is in machine native byte order but may not be in -fully-normalised form if read from an untrusted source. See -g_variant_get_normal_form() for a solution. - -As with g_variant_get_data(), to be able to deserialise the -serialised variant successfully, its type and (if the destination -machine might be different) its endianness must also be available. - -This function is approximately O(n) in the size of @data. - - - - - - - the #GVariant to store - - - - the location to store the serialised data at - - - - - - If @value is floating, sink it. Otherwise, do nothing. - -Typically you want to use g_variant_ref_sink() in order to -automatically do the correct thing with respect to floating or -non-floating references, but there is one specific scenario where -this function is helpful. - -The situation where this function is helpful is when creating an API -that allows the user to provide a callback function that returns a -#GVariant. We certainly want to allow the user the flexibility to -return a non-floating reference from this callback (for the case -where the value that is being returned already exists). - -At the same time, the style of the #GVariant API makes it likely that -for newly-created #GVariant instances, the user can be saved some -typing if they are allowed to return a #GVariant with a floating -reference. - -Using this function on the return value of the user's callback allows -the user to do whichever is more convenient for them. The caller -will alway receives exactly one full reference to the value: either -the one that was returned in the first place, or a floating reference -that has been converted to a full reference. - -This function has an odd interaction when combined with -g_variant_ref_sink() running at the same time in another thread on -the same #GVariant instance. If g_variant_ref_sink() runs first then -the result will be that the floating reference is converted to a hard -reference. If g_variant_take_ref() runs first then the result will -be that the floating reference is converted to a hard reference and -an additional reference on top of that one is added. It is best to -avoid this situation. - - - the same @value - - - - - a #GVariant - - - - - - Decreases the reference count of @value. When its reference count -drops to 0, the memory used by the variant is freed. - - - - - - - a #GVariant - - - - - - Determines if a given string is a valid D-Bus object path. You -should ensure that a string is a valid D-Bus object path before -passing it to g_variant_new_object_path(). - -A valid object path starts with `/` followed by zero or more -sequences of characters separated by `/` characters. Each sequence -must contain only the characters `[A-Z][a-z][0-9]_`. No sequence -(including the one following the final `/` character) may be empty. - - - %TRUE if @string is a D-Bus object path - - - - - a normal C nul-terminated string - - - - - - Determines if a given string is a valid D-Bus type signature. You -should ensure that a string is a valid D-Bus type signature before -passing it to g_variant_new_signature(). - -D-Bus type signatures consist of zero or more definite #GVariantType -strings in sequence. - - - %TRUE if @string is a D-Bus type signature - - - - - a normal C nul-terminated string - - - - - - Parses a #GVariant from a text representation. - -A single #GVariant is parsed from the content of @text. - -The format is described [here][gvariant-text]. - -The memory at @limit will never be accessed and the parser behaves as -if the character at @limit is the nul terminator. This has the -effect of bounding @text. - -If @endptr is non-%NULL then @text is permitted to contain data -following the value that this function parses and @endptr will be -updated to point to the first character past the end of the text -parsed by this function. If @endptr is %NULL and there is extra data -then an error is returned. - -If @type is non-%NULL then the value will be parsed to have that -type. This may result in additional parse errors (in the case that -the parsed value doesn't fit the type) but may also result in fewer -errors (in the case that the type would have been ambiguous, such as -with empty arrays). - -In the event that the parsing is successful, the resulting #GVariant -is returned. It is never floating, and must be freed with -g_variant_unref(). - -In case of any error, %NULL will be returned. If @error is non-%NULL -then it will be set to reflect the error that occurred. - -Officially, the language understood by the parser is "any string -produced by g_variant_print()". - -There may be implementation specific restrictions on deeply nested values, -which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is -guaranteed to handle nesting up to at least 64 levels. - - - a non-floating reference to a #GVariant, or %NULL - - - - - a #GVariantType, or %NULL - - - - a string containing a GVariant in text form - - - - a pointer to the end of @text, or %NULL - - - - a location to store the end pointer, or %NULL - - - - - - Pretty-prints a message showing the context of a #GVariant parse -error within the string for which parsing was attempted. - -The resulting string is suitable for output to the console or other -monospace media where newlines are treated in the usual way. - -The message will typically look something like one of the following: - -|[ -unterminated string constant: - (1, 2, 3, 'abc - ^^^^ -]| - -or - -|[ -unable to find a common type: - [1, 2, 3, 'str'] - ^ ^^^^^ -]| - -The format of the message may change in a future version. - -@error must have come from a failed attempt to g_variant_parse() and -@source_str must be exactly the same string that caused the error. -If @source_str was not nul-terminated when you passed it to -g_variant_parse() then you must add nul termination before using this -function. - - - the printed message - - - - - a #GError from the #GVariantParseError domain - - - - the string that was given to the parser - - - - - - - - - - - Same as g_variant_error_quark(). - Use g_variant_parse_error_quark() instead. - - - - - - - A utility type for constructing container-type #GVariant instances. - -This is an opaque structure and may only be accessed using the -following functions. - -#GVariantBuilder is not threadsafe in any way. Do not attempt to -access it from more than one thread. - - - - - - - - - - - - - - - - - - - - - - - - - Allocates and initialises a new #GVariantBuilder. - -You should call g_variant_builder_unref() on the return value when it -is no longer needed. The memory will not be automatically freed by -any other call. - -In most cases it is easier to place a #GVariantBuilder directly on -the stack of the calling function and initialise it with -g_variant_builder_init(). - - - a #GVariantBuilder - - - - - a container type - - - - - - Adds to a #GVariantBuilder. - -This call is a convenience wrapper that is exactly equivalent to -calling g_variant_new() followed by g_variant_builder_add_value(). - -Note that the arguments must be of the correct width for their types -specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. - -This function might be used as follows: - -|[<!-- language="C" --> -GVariant * -make_pointless_dictionary (void) -{ - GVariantBuilder builder; - int i; - - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); - for (i = 0; i < 16; i++) - { - gchar buf[3]; - - sprintf (buf, "%d", i); - g_variant_builder_add (&builder, "{is}", i, buf); - } - - return g_variant_builder_end (&builder); -} -]| - - - - - - - a #GVariantBuilder - - - - a #GVariant varargs format string - - - - arguments, as per @format_string - - - - - - Adds to a #GVariantBuilder. - -This call is a convenience wrapper that is exactly equivalent to -calling g_variant_new_parsed() followed by -g_variant_builder_add_value(). - -Note that the arguments must be of the correct width for their types -specified in @format_string. This can be achieved by casting them. See -the [GVariant varargs documentation][gvariant-varargs]. - -This function might be used as follows: - -|[<!-- language="C" --> -GVariant * -make_pointless_dictionary (void) -{ - GVariantBuilder builder; - int i; - - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); - g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); - g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); - g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); - return g_variant_builder_end (&builder); -} -]| - - - - - - - a #GVariantBuilder - - - - a text format #GVariant - - - - arguments as per @format - - - - - - Adds @value to @builder. - -It is an error to call this function in any way that would create an -inconsistent value to be constructed. Some examples of this are -putting different types of items into an array, putting the wrong -types or number of items in a tuple, putting more than one value into -a variant, etc. - -If @value is a floating reference (see g_variant_ref_sink()), -the @builder instance takes ownership of @value. - - - - - - - a #GVariantBuilder - - - - a #GVariant - - - - - - Releases all memory associated with a #GVariantBuilder without -freeing the #GVariantBuilder structure itself. - -It typically only makes sense to do this on a stack-allocated -#GVariantBuilder if you want to abort building the value part-way -through. This function need not be called if you call -g_variant_builder_end() and it also doesn't need to be called on -builders allocated with g_variant_builder_new() (see -g_variant_builder_unref() for that). - -This function leaves the #GVariantBuilder structure set to all-zeros. -It is valid to call this function on either an initialised -#GVariantBuilder or one that is set to all-zeros but it is not valid -to call this function on uninitialised memory. - - - - - - - a #GVariantBuilder - - - - - - Closes the subcontainer inside the given @builder that was opened by -the most recent call to g_variant_builder_open(). - -It is an error to call this function in any way that would create an -inconsistent value to be constructed (ie: too few values added to the -subcontainer). - - - - - - - a #GVariantBuilder - - - - - - Ends the builder process and returns the constructed value. - -It is not permissible to use @builder in any way after this call -except for reference counting operations (in the case of a -heap-allocated #GVariantBuilder) or by reinitialising it with -g_variant_builder_init() (in the case of stack-allocated). This -means that for the stack-allocated builders there is no need to -call g_variant_builder_clear() after the call to -g_variant_builder_end(). - -It is an error to call this function in any way that would create an -inconsistent value to be constructed (ie: insufficient number of -items added to a container with a specific number of children -required). It is also an error to call this function if the builder -was created with an indefinite array or maybe type and no children -have been added; in this case it is impossible to infer the type of -the empty array. - - - a new, floating, #GVariant - - - - - a #GVariantBuilder - - - - - - Initialises a #GVariantBuilder structure. - -@type must be non-%NULL. It specifies the type of container to -construct. It can be an indefinite type such as -%G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". -Maybe, array, tuple, dictionary entry and variant-typed values may be -constructed. - -After the builder is initialised, values are added using -g_variant_builder_add_value() or g_variant_builder_add(). - -After all the child values are added, g_variant_builder_end() frees -the memory associated with the builder and returns the #GVariant that -was created. - -This function completely ignores the previous contents of @builder. -On one hand this means that it is valid to pass in completely -uninitialised memory. On the other hand, this means that if you are -initialising over top of an existing #GVariantBuilder you need to -first call g_variant_builder_clear() in order to avoid leaking -memory. - -You must not call g_variant_builder_ref() or -g_variant_builder_unref() on a #GVariantBuilder that was initialised -with this function. If you ever pass a reference to a -#GVariantBuilder outside of the control of your own code then you -should assume that the person receiving that reference may try to use -reference counting; you should use g_variant_builder_new() instead of -this function. - - - - - - - a #GVariantBuilder - - - - a container type - - - - - - Opens a subcontainer inside the given @builder. When done adding -items to the subcontainer, g_variant_builder_close() must be called. @type -is the type of the container: so to build a tuple of several values, @type -must include the tuple itself. - -It is an error to call this function in any way that would cause an -inconsistent value to be constructed (ie: adding too many values or -a value of an incorrect type). - -Example of building a nested variant: -|[<!-- language="C" --> -GVariantBuilder builder; -guint32 some_number = get_number (); -g_autoptr (GHashTable) some_dict = get_dict (); -GHashTableIter iter; -const gchar *key; -const GVariant *value; -g_autoptr (GVariant) output = NULL; - -g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); -g_variant_builder_add (&builder, "u", some_number); -g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); - -g_hash_table_iter_init (&iter, some_dict); -while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) - { - g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); - g_variant_builder_add (&builder, "s", key); - g_variant_builder_add (&builder, "v", value); - g_variant_builder_close (&builder); - } - -g_variant_builder_close (&builder); - -output = g_variant_builder_end (&builder); -]| - - - - - - - a #GVariantBuilder - - - - the #GVariantType of the container - - - - - - Increases the reference count on @builder. - -Don't call this on stack-allocated #GVariantBuilder instances or bad -things will happen. - - - a new reference to @builder - - - - - a #GVariantBuilder allocated by g_variant_builder_new() - - - - - - Decreases the reference count on @builder. - -In the event that there are no more references, releases all memory -associated with the #GVariantBuilder. - -Don't call this on stack-allocated #GVariantBuilder instances or bad -things will happen. - - - - - - - a #GVariantBuilder allocated by g_variant_builder_new() - - - - - - - The range of possible top-level types of #GVariant instances. - - - The #GVariant is a boolean. - - - The #GVariant is a byte. - - - The #GVariant is a signed 16 bit integer. - - - The #GVariant is an unsigned 16 bit integer. - - - The #GVariant is a signed 32 bit integer. - - - The #GVariant is an unsigned 32 bit integer. - - - The #GVariant is a signed 64 bit integer. - - - The #GVariant is an unsigned 64 bit integer. - - - The #GVariant is a file handle index. - - - The #GVariant is a double precision floating - point value. - - - The #GVariant is a normal string. - - - The #GVariant is a D-Bus object path - string. - - - The #GVariant is a D-Bus signature string. - - - The #GVariant is a variant. - - - The #GVariant is a maybe-typed value. - - - The #GVariant is an array. - - - The #GVariant is a tuple. - - - The #GVariant is a dictionary entry. - - - - #GVariantDict is a mutable interface to #GVariant dictionaries. - -It can be used for doing a sequence of dictionary lookups in an -efficient way on an existing #GVariant dictionary or it can be used -to construct new dictionaries with a hashtable-like interface. It -can also be used for taking existing dictionaries and modifying them -in order to create new ones. - -#GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT -dictionaries. - -It is possible to use #GVariantDict allocated on the stack or on the -heap. When using a stack-allocated #GVariantDict, you begin with a -call to g_variant_dict_init() and free the resources with a call to -g_variant_dict_clear(). - -Heap-allocated #GVariantDict follows normal refcounting rules: you -allocate it with g_variant_dict_new() and use g_variant_dict_ref() -and g_variant_dict_unref(). - -g_variant_dict_end() is used to convert the #GVariantDict back into a -dictionary-type #GVariant. When used with stack-allocated instances, -this also implicitly frees all associated memory, but for -heap-allocated instances, you must still call g_variant_dict_unref() -afterwards. - -You will typically want to use a heap-allocated #GVariantDict when -you expose it as part of an API. For most other uses, the -stack-allocated form will be more convenient. - -Consider the following two examples that do the same thing in each -style: take an existing dictionary and look up the "count" uint32 -key, adding 1 to it if it is found, or returning an error if the -key is not found. Each returns the new dictionary as a floating -#GVariant. - -## Using a stack-allocated GVariantDict - -|[<!-- language="C" --> - GVariant * - add_to_count (GVariant *orig, - GError **error) - { - GVariantDict dict; - guint32 count; - - g_variant_dict_init (&dict, orig); - if (!g_variant_dict_lookup (&dict, "count", "u", &count)) - { - g_set_error (...); - g_variant_dict_clear (&dict); - return NULL; - } - - g_variant_dict_insert (&dict, "count", "u", count + 1); - - return g_variant_dict_end (&dict); - } -]| - -## Using heap-allocated GVariantDict - -|[<!-- language="C" --> - GVariant * - add_to_count (GVariant *orig, - GError **error) - { - GVariantDict *dict; - GVariant *result; - guint32 count; - - dict = g_variant_dict_new (orig); - - if (g_variant_dict_lookup (dict, "count", "u", &count)) - { - g_variant_dict_insert (dict, "count", "u", count + 1); - result = g_variant_dict_end (dict); - } - else - { - g_set_error (...); - result = NULL; - } - - g_variant_dict_unref (dict); - - return result; - } -]| - - - - - - - - - - - - - - - - - - - - - - - - - Allocates and initialises a new #GVariantDict. - -You should call g_variant_dict_unref() on the return value when it -is no longer needed. The memory will not be automatically freed by -any other call. - -In some cases it may be easier to place a #GVariantDict directly on -the stack of the calling function and initialise it with -g_variant_dict_init(). This is particularly useful when you are -using #GVariantDict to construct a #GVariant. - - - a #GVariantDict - - - - - the #GVariant with which to initialise the - dictionary - - - - - - Releases all memory associated with a #GVariantDict without freeing -the #GVariantDict structure itself. - -It typically only makes sense to do this on a stack-allocated -#GVariantDict if you want to abort building the value part-way -through. This function need not be called if you call -g_variant_dict_end() and it also doesn't need to be called on dicts -allocated with g_variant_dict_new (see g_variant_dict_unref() for -that). - -It is valid to call this function on either an initialised -#GVariantDict or one that was previously cleared by an earlier call -to g_variant_dict_clear() but it is not valid to call this function -on uninitialised memory. - - - - - - - a #GVariantDict - - - - - - Checks if @key exists in @dict. - - - %TRUE if @key is in @dict - - - - - a #GVariantDict - - - - the key to look up in the dictionary - - - - - - Returns the current value of @dict as a #GVariant of type -%G_VARIANT_TYPE_VARDICT, clearing it in the process. - -It is not permissible to use @dict in any way after this call except -for reference counting operations (in the case of a heap-allocated -#GVariantDict) or by reinitialising it with g_variant_dict_init() (in -the case of stack-allocated). - - - a new, floating, #GVariant - - - - - a #GVariantDict - - - - - - Initialises a #GVariantDict structure. - -If @from_asv is given, it is used to initialise the dictionary. - -This function completely ignores the previous contents of @dict. On -one hand this means that it is valid to pass in completely -uninitialised memory. On the other hand, this means that if you are -initialising over top of an existing #GVariantDict you need to first -call g_variant_dict_clear() in order to avoid leaking memory. - -You must not call g_variant_dict_ref() or g_variant_dict_unref() on a -#GVariantDict that was initialised with this function. If you ever -pass a reference to a #GVariantDict outside of the control of your -own code then you should assume that the person receiving that -reference may try to use reference counting; you should use -g_variant_dict_new() instead of this function. - - - - - - - a #GVariantDict - - - - the initial value for @dict - - - - - - Inserts a value into a #GVariantDict. - -This call is a convenience wrapper that is exactly equivalent to -calling g_variant_new() followed by g_variant_dict_insert_value(). - - - - - - - a #GVariantDict - - - - the key to insert a value for - - - - a #GVariant varargs format string - - - - arguments, as per @format_string - - - - - - Inserts (or replaces) a key in a #GVariantDict. - -@value is consumed if it is floating. - - - - - - - a #GVariantDict - - - - the key to insert a value for - - - - the value to insert - - - - - - Looks up a value in a #GVariantDict. - -This function is a wrapper around g_variant_dict_lookup_value() and -g_variant_get(). In the case that %NULL would have been returned, -this function returns %FALSE. Otherwise, it unpacks the returned -value and returns %TRUE. - -@format_string determines the C types that are used for unpacking the -values and also determines if the values are copied or borrowed, see the -section on [GVariant format strings][gvariant-format-strings-pointers]. - - - %TRUE if a value was unpacked - - - - - a #GVariantDict - - - - the key to look up in the dictionary - - - - a GVariant format string - - - - the arguments to unpack the value into - - - - - - Looks up a value in a #GVariantDict. - -If @key is not found in @dictionary, %NULL is returned. - -The @expected_type string specifies what type of value is expected. -If the value associated with @key has a different type then %NULL is -returned. - -If the key is found and the value has the correct type, it is -returned. If @expected_type was specified then any non-%NULL return -value will have this type. - - - the value of the dictionary key, or %NULL - - - - - a #GVariantDict - - - - the key to look up in the dictionary - - - - a #GVariantType, or %NULL - - - - - - Increases the reference count on @dict. - -Don't call this on stack-allocated #GVariantDict instances or bad -things will happen. - - - a new reference to @dict - - - - - a heap-allocated #GVariantDict - - - - - - Removes a key and its associated value from a #GVariantDict. - - - %TRUE if the key was found and removed - - - - - a #GVariantDict - - - - the key to remove - - - - - - Decreases the reference count on @dict. - -In the event that there are no more references, releases all memory -associated with the #GVariantDict. - -Don't call this on stack-allocated #GVariantDict instances or bad -things will happen. - - - - - - - a heap-allocated #GVariantDict - - - - - - - #GVariantIter is an opaque data structure and can only be accessed -using the following functions. - - - - - - - - Creates a new heap-allocated #GVariantIter to iterate over the -container that was being iterated over by @iter. Iteration begins on -the new iterator from the current position of the old iterator but -the two copies are independent past that point. - -Use g_variant_iter_free() to free the return value when you no longer -need it. - -A reference is taken to the container that @iter is iterating over -and will be releated only when g_variant_iter_free() is called. - - - a new heap-allocated #GVariantIter - - - - - a #GVariantIter - - - - - - Frees a heap-allocated #GVariantIter. Only call this function on -iterators that were returned by g_variant_iter_new() or -g_variant_iter_copy(). - - - - - - - a heap-allocated #GVariantIter - - - - - - Initialises (without allocating) a #GVariantIter. @iter may be -completely uninitialised prior to this call; its old value is -ignored. - -The iterator remains valid for as long as @value exists, and need not -be freed in any way. - - - the number of items in @value - - - - - a pointer to a #GVariantIter - - - - a container #GVariant - - - - - - Gets the next item in the container and unpacks it into the variable -argument list according to @format_string, returning %TRUE. - -If no more items remain then %FALSE is returned. - -On the first call to this function, the pointers appearing on the -variable argument list are assumed to point at uninitialised memory. -On the second and later calls, it is assumed that the same pointers -will be given and that they will point to the memory as set by the -previous call to this function. This allows the previous values to -be freed, as appropriate. - -This function is intended to be used with a while loop as -demonstrated in the following example. This function can only be -used when iterating over an array. It is only valid to call this -function with a string constant for the format string and the same -string constant must be used each time. Mixing calls to this -function and g_variant_iter_next() or g_variant_iter_next_value() on -the same iterator causes undefined behavior. - -If you break out of a such a while loop using g_variant_iter_loop() then -you must free or unreference all the unpacked values as you would with -g_variant_get(). Failure to do so will cause a memory leak. - -Here is an example for memory management with g_variant_iter_loop(): -|[<!-- language="C" --> - // Iterates a dictionary of type 'a{sv}' - void - iterate_dictionary (GVariant *dictionary) - { - GVariantIter iter; - GVariant *value; - gchar *key; - - g_variant_iter_init (&iter, dictionary); - while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) - { - g_print ("Item '%s' has type '%s'\n", key, - g_variant_get_type_string (value)); - - // no need to free 'key' and 'value' here - // unless breaking out of this loop - } - } -]| - -For most cases you should use g_variant_iter_next(). - -This function is really only useful when unpacking into #GVariant or -#GVariantIter in order to allow you to skip the call to -g_variant_unref() or g_variant_iter_free(). - -For example, if you are only looping over simple integer and string -types, g_variant_iter_next() is definitely preferred. For string -types, use the '&' prefix to avoid allocating any memory at all (and -thereby avoiding the need to free anything as well). - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed. - -See the section on -[GVariant format strings][gvariant-format-strings-pointers]. - - - %TRUE if a value was unpacked, or %FALSE if there was no - value - - - - - a #GVariantIter - - - - a GVariant format string - - - - the arguments to unpack the value into - - - - - - Queries the number of child items in the container that we are -iterating over. This is the total number of items -- not the number -of items remaining. - -This function might be useful for preallocation of arrays. - - - the number of children in the container - - - - - a #GVariantIter - - - - - - Gets the next item in the container and unpacks it into the variable -argument list according to @format_string, returning %TRUE. - -If no more items remain then %FALSE is returned. - -All of the pointers given on the variable arguments list of this -function are assumed to point at uninitialised memory. It is the -responsibility of the caller to free all of the values returned by -the unpacking process. - -Here is an example for memory management with g_variant_iter_next(): -|[<!-- language="C" --> - // Iterates a dictionary of type 'a{sv}' - void - iterate_dictionary (GVariant *dictionary) - { - GVariantIter iter; - GVariant *value; - gchar *key; - - g_variant_iter_init (&iter, dictionary); - while (g_variant_iter_next (&iter, "{sv}", &key, &value)) - { - g_print ("Item '%s' has type '%s'\n", key, - g_variant_get_type_string (value)); - - // must free data for ourselves - g_variant_unref (value); - g_free (key); - } - } -]| - -For a solution that is likely to be more convenient to C programmers -when dealing with loops, see g_variant_iter_loop(). - -@format_string determines the C types that are used for unpacking -the values and also determines if the values are copied or borrowed. - -See the section on -[GVariant format strings][gvariant-format-strings-pointers]. - - - %TRUE if a value was unpacked, or %FALSE if there as no value - - - - - a #GVariantIter - - - - a GVariant format string - - - - the arguments to unpack the value into - - - - - - Gets the next item in the container. If no more items remain then -%NULL is returned. - -Use g_variant_unref() to drop your reference on the return value when -you no longer need it. - -Here is an example for iterating with g_variant_iter_next_value(): -|[<!-- language="C" --> - // recursively iterate a container - void - iterate_container_recursive (GVariant *container) - { - GVariantIter iter; - GVariant *child; - - g_variant_iter_init (&iter, container); - while ((child = g_variant_iter_next_value (&iter))) - { - g_print ("type '%s'\n", g_variant_get_type_string (child)); - - if (g_variant_is_container (child)) - iterate_container_recursive (child); - - g_variant_unref (child); - } - } -]| - - - a #GVariant, or %NULL - - - - - a #GVariantIter - - - - - - - Error codes returned by parsing text-format GVariants. - - - generic error (unused) - - - a non-basic #GVariantType was given where a basic type was expected - - - cannot infer the #GVariantType - - - an indefinite #GVariantType was given where a definite type was expected - - - extra data after parsing finished - - - invalid character in number or unicode escape - - - not a valid #GVariant format string - - - not a valid object path - - - not a valid type signature - - - not a valid #GVariant type string - - - could not find a common type for array entries - - - the numerical value is out of range of the given type - - - the numerical value is out of range for any type - - - cannot parse as variant of the specified type - - - an unexpected token was encountered - - - an unknown keyword was encountered - - - unterminated string constant - - - no value given - - - variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) - - - - This section introduces the GVariant type system. It is based, in -large part, on the D-Bus type system, with two major changes and -some minor lifting of restrictions. The -[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), -therefore, provides a significant amount of -information that is useful when working with GVariant. - -The first major change with respect to the D-Bus type system is the -introduction of maybe (or "nullable") types. Any type in GVariant can be -converted to a maybe type, in which case, "nothing" (or "null") becomes a -valid value. Maybe types have been added by introducing the -character "m" to type strings. - -The second major change is that the GVariant type system supports the -concept of "indefinite types" -- types that are less specific than -the normal types found in D-Bus. For example, it is possible to speak -of "an array of any type" in GVariant, where the D-Bus type system -would require you to speak of "an array of integers" or "an array of -strings". Indefinite types have been added by introducing the -characters "*", "?" and "r" to type strings. - -Finally, all arbitrary restrictions relating to the complexity of -types are lifted along with the restriction that dictionary entries -may only appear nested inside of arrays. - -Just as in D-Bus, GVariant types are described with strings ("type -strings"). Subject to the differences mentioned above, these strings -are of the same form as those found in DBus. Note, however: D-Bus -always works in terms of messages and therefore individual type -strings appear nowhere in its interface. Instead, "signatures" -are a concatenation of the strings of the type of each argument in a -message. GVariant deals with single values directly so GVariant type -strings always describe the type of exactly one value. This means -that a D-Bus signature string is generally not a valid GVariant type -string -- except in the case that it is the signature of a message -containing exactly one argument. - -An indefinite type is similar in spirit to what may be called an -abstract type in other type systems. No value can exist that has an -indefinite type as its type, but values can exist that have types -that are subtypes of indefinite types. That is to say, -g_variant_get_type() will never return an indefinite type, but -calling g_variant_is_of_type() with an indefinite type may return -%TRUE. For example, you cannot have a value that represents "an -array of no particular type", but you can have an "array of integers" -which certainly matches the type of "an array of no particular type", -since "array of integers" is a subtype of "array of no particular -type". - -This is similar to how instances of abstract classes may not -directly exist in other type systems, but instances of their -non-abstract subtypes may. For example, in GTK, no object that has -the type of #GtkBin can exist (since #GtkBin is an abstract class), -but a #GtkWindow can certainly be instantiated, and you would say -that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of -#GtkBin). - -## GVariant Type Strings - -A GVariant type string can be any of the following: - -- any basic type string (listed below) - -- "v", "r" or "*" - -- one of the characters 'a' or 'm', followed by another type string - -- the character '(', followed by a concatenation of zero or more other - type strings, followed by the character ')' - -- the character '{', followed by a basic type string (see below), - followed by another type string, followed by the character '}' - -A basic type string describes a basic type (as per -g_variant_type_is_basic()) and is always a single character in length. -The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", -"h", "d", "s", "o", "g" and "?". - -The above definition is recursive to arbitrary depth. "aaaaai" and -"(ui(nq((y)))s)" are both valid type strings, as is -"a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant -imposes a limit on recursion depth of 65 nested containers. This is the -limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to -be nested in a top-level tuple. - -The meaning of each of the characters is as follows: -- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. -- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. -- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. -- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. -- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. -- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. -- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. -- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. -- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value - that, by convention, is used as an index into an array of file - descriptors that are sent alongside a D-Bus message. -- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision - floating point value. -- `s`: the type string of %G_VARIANT_TYPE_STRING; a string. -- `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form - of a D-Bus object path. -- `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of - a D-Bus type signature. -- `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that - is a supertype of any of the basic types. -- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that - contain any other type of value. -- `a`: used as a prefix on another type string to mean an array of that - type; the type string "ai", for example, is the type of an array of - signed 32-bit integers. -- `m`: used as a prefix on another type string to mean a "maybe", or - "nullable", version of that type; the type string "ms", for example, - is the type of a value that maybe contains a string, or maybe contains - nothing. -- `()`: used to enclose zero or more other concatenated type strings to - create a tuple type; the type string "(is)", for example, is the type of - a pair of an integer and a string. -- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is - a supertype of any tuple type, regardless of the number of items. -- `{}`: used to enclose a basic type string concatenated with another type - string to create a dictionary entry type, which usually appears inside of - an array to form a dictionary; the type string "a{sd}", for example, is - the type of a dictionary that maps strings to double precision floating - point values. - - The first type (the basic type) is the key type and the second type is - the value type. The reason that the first type is restricted to being a - basic type is so that it can easily be hashed. -- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is - a supertype of all types. Note that, as with all type strings, this - character represents exactly one type. It cannot be used inside of tuples - to mean "any number of items". - -Any type string of a container that contains an indefinite type is, -itself, an indefinite type. For example, the type string "a*" -(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type -that is a supertype of every array type. "(*s)" is a supertype -of all tuples that contain exactly two items where the second -item is a string. - -"a{?*}" is an indefinite type that is a supertype of all arrays -containing dictionary entries where the key is any basic type and -the value is any type at all. This is, by definition, a dictionary, -so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note -that, due to the restriction that the key of a dictionary entry must -be a basic type, "{**}" is not a valid type string. - - - Creates a new #GVariantType corresponding to the type string given -by @type_string. It is appropriate to call g_variant_type_free() on -the return value. - -It is a programmer error to call this function with an invalid type -string. Use g_variant_type_string_is_valid() if you are unsure. - - - a new #GVariantType - - - - - a valid GVariant type string - - - - - - Constructs the type corresponding to an array of elements of the -type @type. - -It is appropriate to call g_variant_type_free() on the return value. - - - a new array #GVariantType - -Since 2.24 - - - - - a #GVariantType - - - - - - Constructs the type corresponding to a dictionary entry with a key -of type @key and a value of type @value. - -It is appropriate to call g_variant_type_free() on the return value. - - - a new dictionary entry #GVariantType - -Since 2.24 - - - - - a basic #GVariantType - - - - a #GVariantType - - - - - - Constructs the type corresponding to a maybe instance containing -type @type or Nothing. - -It is appropriate to call g_variant_type_free() on the return value. - - - a new maybe #GVariantType - -Since 2.24 - - - - - a #GVariantType - - - - - - Constructs a new tuple type, from @items. - -@length is the number of items in @items, or -1 to indicate that -@items is %NULL-terminated. - -It is appropriate to call g_variant_type_free() on the return value. - - - a new tuple #GVariantType - -Since 2.24 - - - - - an array of #GVariantTypes, one for each item - - - - - - the length of @items, or -1 - - - - - - Makes a copy of a #GVariantType. It is appropriate to call -g_variant_type_free() on the return value. @type may not be %NULL. - - - a new #GVariantType - -Since 2.24 - - - - - a #GVariantType - - - - - - Returns a newly-allocated copy of the type string corresponding to -@type. The returned string is nul-terminated. It is appropriate to -call g_free() on the return value. - - - the corresponding type string - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines the element type of an array or maybe type. - -This function may only be used with array or maybe types. - - - the element type of @type - -Since 2.24 - - - - - an array or maybe #GVariantType - - - - - - Compares @type1 and @type2 for equality. - -Only returns %TRUE if the types are exactly equal. Even if one type -is an indefinite type and the other is a subtype of it, %FALSE will -be returned if they are not exactly equal. If you want to check for -subtypes, use g_variant_type_is_subtype_of(). - -The argument types of @type1 and @type2 are only #gconstpointer to -allow use with #GHashTable without function pointer casting. For -both arguments, a valid #GVariantType must be provided. - - - %TRUE if @type1 and @type2 are exactly equal - -Since 2.24 - - - - - a #GVariantType - - - - a #GVariantType - - - - - - Determines the first item type of a tuple or dictionary entry -type. - -This function may only be used with tuple or dictionary entry types, -but must not be used with the generic tuple type -%G_VARIANT_TYPE_TUPLE. - -In the case of a dictionary entry type, this returns the type of -the key. - -%NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. - -This call, together with g_variant_type_next() provides an iterator -interface over tuple and dictionary entry types. - - - the first item type of @type, or %NULL - -Since 2.24 - - - - - a tuple or dictionary entry #GVariantType - - - - - - Frees a #GVariantType that was allocated with -g_variant_type_copy(), g_variant_type_new() or one of the container -type constructor functions. - -In the case that @type is %NULL, this function does nothing. - -Since 2.24 - - - - - - - a #GVariantType, or %NULL - - - - - - Returns the length of the type string corresponding to the given -@type. This function must be used to determine the valid extent of -the memory region returned by g_variant_type_peek_string(). - - - the length of the corresponding type string - -Since 2.24 - - - - - a #GVariantType - - - - - - Hashes @type. - -The argument type of @type is only #gconstpointer to allow use with -#GHashTable without function pointer casting. A valid -#GVariantType must be provided. - - - the hash value - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is an array type. This is true if the -type string for @type starts with an 'a'. - -This function returns %TRUE for any indefinite type for which every -definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for -example. - - - %TRUE if @type is an array type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is a basic type. - -Basic types are booleans, bytes, integers, doubles, strings, object -paths and signatures. - -Only a basic type may be used as the key of a dictionary entry. - -This function returns %FALSE for all indefinite types except -%G_VARIANT_TYPE_BASIC. - - - %TRUE if @type is a basic type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is a container type. - -Container types are any array, maybe, tuple, or dictionary -entry types plus the variant type. - -This function returns %TRUE for any indefinite type for which every -definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for -example. - - - %TRUE if @type is a container type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is definite (ie: not indefinite). - -A type is definite if its type string does not contain any indefinite -type characters ('*', '?', or 'r'). - -A #GVariant instance may not have an indefinite type, so calling -this function on the result of g_variant_get_type() will always -result in %TRUE being returned. Calling this function on an -indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in -%FALSE being returned. - - - %TRUE if @type is definite - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is a dictionary entry type. This is -true if the type string for @type starts with a '{'. - -This function returns %TRUE for any indefinite type for which every -definite subtype is a dictionary entry type -- -%G_VARIANT_TYPE_DICT_ENTRY, for example. - - - %TRUE if @type is a dictionary entry type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is a maybe type. This is true if the -type string for @type starts with an 'm'. - -This function returns %TRUE for any indefinite type for which every -definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for -example. - - - %TRUE if @type is a maybe type - -Since 2.24 - - - - - a #GVariantType - - - - - - Checks if @type is a subtype of @supertype. - -This function returns %TRUE if @type is a subtype of @supertype. All -types are considered to be subtypes of themselves. Aside from that, -only indefinite types can have subtypes. - - - %TRUE if @type is a subtype of @supertype - -Since 2.24 - - - - - a #GVariantType - - - - a #GVariantType - - - - - - Determines if the given @type is a tuple type. This is true if the -type string for @type starts with a '(' or if @type is -%G_VARIANT_TYPE_TUPLE. - -This function returns %TRUE for any indefinite type for which every -definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for -example. - - - %TRUE if @type is a tuple type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines if the given @type is the variant type. - - - %TRUE if @type is the variant type - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines the key type of a dictionary entry type. - -This function may only be used with a dictionary entry type. Other -than the additional restriction, this call is equivalent to -g_variant_type_first(). - - - the key type of the dictionary entry - -Since 2.24 - - - - - a dictionary entry #GVariantType - - - - - - Determines the number of items contained in a tuple or -dictionary entry type. - -This function may only be used with tuple or dictionary entry types, -but must not be used with the generic tuple type -%G_VARIANT_TYPE_TUPLE. - -In the case of a dictionary entry type, this function will always -return 2. - - - the number of items in @type - -Since 2.24 - - - - - a tuple or dictionary entry #GVariantType - - - - - - Determines the next item type of a tuple or dictionary entry -type. - -@type must be the result of a previous call to -g_variant_type_first() or g_variant_type_next(). - -If called on the key type of a dictionary entry then this call -returns the value type. If called on the value type of a dictionary -entry then this call returns %NULL. - -For tuples, %NULL is returned when @type is the last item in a tuple. - - - the next #GVariantType after @type, or %NULL - -Since 2.24 - - - - - a #GVariantType from a previous call - - - - - - Returns the type string corresponding to the given @type. The -result is not nul-terminated; in order to determine its length you -must call g_variant_type_get_string_length(). - -To get a nul-terminated string, see g_variant_type_dup_string(). - - - the corresponding type string (not nul-terminated) - -Since 2.24 - - - - - a #GVariantType - - - - - - Determines the value type of a dictionary entry type. - -This function may only be used with a dictionary entry type. - - - the value type of the dictionary entry - -Since 2.24 - - - - - a dictionary entry #GVariantType - - - - - - - - - - - - - - - - - - - - - - - - - - - - Checks if @type_string is a valid GVariant type string. This call is -equivalent to calling g_variant_type_string_scan() and confirming -that the following character is a nul terminator. - - - %TRUE if @type_string is exactly one valid type string - -Since 2.24 - - - - - a pointer to any string - - - - - - Scan for a single complete and valid GVariant type string in @string. -The memory pointed to by @limit (or bytes beyond it) is never -accessed. - -If a valid type string is found, @endptr is updated to point to the -first character past the end of the string that was found and %TRUE -is returned. - -If there is no valid type string starting at @string, or if the type -string does not end before @limit then %FALSE is returned. - -For the simple case of checking if a string is a valid type string, -see g_variant_type_string_is_valid(). - - - %TRUE if a valid type string was found - - - - - a pointer to any string - - - - the end of @string, or %NULL - - - - location to store the end pointer, or %NULL - - - - - - - Declares a type of function which takes no arguments -and has no return value. It is used to specify the type -function passed to g_atexit(). - - - - - - - On Windows, this macro defines a DllMain() function that stores -the actual DLL name that the code being compiled will be included in. - -On non-Windows platforms, expands to nothing. - - - - empty or "static" - - - the name of the (pointer to the) char array where - the DLL name will be stored. If this is used, you must also - include `windows.h`. If you need a more complex DLL entry - point function, you cannot use this - - - - - - - - - A wrapper for the POSIX access() function. This function is used to -test a pathname for one or several of read, write or execute -permissions, or just existence. - -On Windows, the file protection mechanism is not at all POSIX-like, -and the underlying function in the C library only checks the -FAT-style READONLY attribute, and does not look at the ACL of a -file at all. This function is this in practise almost useless on -Windows. Software that needs to handle file permissions on Windows -more exactly should use the Win32 API. - -See your C library manual for more details about access(). - - - zero if the pathname refers to an existing file system - object that has all the tested permissions, or -1 otherwise - or on error. - - - - - a pathname in the GLib file name encoding - (UTF-8 on Windows) - - - - as in access() - - - - - - Allocates @size bytes on the stack; these bytes will be freed when the current -stack frame is cleaned up. This macro essentially just wraps the alloca() -function present on most UNIX variants. -Thus it provides the same advantages and pitfalls as alloca(): - -- alloca() is very fast, as on most systems it's implemented by just adjusting - the stack pointer register. - -- It doesn't cause any memory fragmentation, within its scope, separate alloca() - blocks just build up and are released together at function end. - -- Allocation sizes have to fit into the current stack frame. For instance in a - threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, - so be sparse with alloca() uses. - -- Allocation failure due to insufficient stack space is not indicated with a %NULL - return like e.g. with malloc(). Instead, most systems probably handle it the same - way as out of stack space situations from infinite function recursion, i.e. - with a segmentation fault. - -- Special care has to be taken when mixing alloca() with GNU C variable sized arrays. - Stack space allocated with alloca() in the same scope as a variable sized array - will be freed together with the variable sized array upon exit of that scope, and - not upon exit of the enclosing function scope. - - - - number of bytes to allocate. - - - - - Adds the value on to the end of the array. The array will grow in -size automatically if necessary. - -g_array_append_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - - - a #GArray - - - the value to append to the #GArray - - - - - Returns the element of a #GArray at the given index. The return -value is cast to the given type. - -This example gets a pointer to an element in a #GArray: -|[<!-- language="C" --> - EDayViewEvent *event; - // This gets a pointer to the 4th element in the array of - // EDayViewEvent structs. - event = &g_array_index (events, EDayViewEvent, 3); -]| - - - - a #GArray - - - the type of the elements - - - the index of the element to return - - - - - Inserts an element into an array at the given index. - -g_array_insert_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - - - a #GArray - - - the index to place the element at - - - the value to insert into the array - - - - - Adds the value on to the start of the array. The array will grow in -size automatically if necessary. - -This operation is slower than g_array_append_val() since the -existing elements in the array have to be moved to make space for -the new element. - -g_array_prepend_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - - - a #GArray - - - the value to prepend to the #GArray - - - - - Determines the numeric value of a character as a decimal digit. -Differs from g_unichar_digit_value() because it takes a char, so -there's no worry about sign extension if characters are signed. - - - If @c is a decimal digit (according to g_ascii_isdigit()), - its numeric value. Otherwise, -1. - - - - - an ASCII character - - - - - - Converts a #gdouble to a string, using the '.' as -decimal point. - -This function generates enough precision that converting -the string back using g_ascii_strtod() gives the same machine-number -(on machines with IEEE compatible 64bit doubles). It is -guaranteed that the size of the resulting string will never -be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating -nul character, which is always added. - - - The pointer to the buffer with the converted string. - - - - - A buffer to place the resulting string in - - - - The length of the buffer. - - - - The #gdouble to convert - - - - - - Converts a #gdouble to a string, using the '.' as -decimal point. To format the number you pass in -a printf()-style format string. Allowed conversion -specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. - -The returned buffer is guaranteed to be nul-terminated. - -If you just want to want to serialize the value into a -string, use g_ascii_dtostr(). - - - The pointer to the buffer with the converted string. - - - - - A buffer to place the resulting string in - - - - The length of the buffer. - - - - The printf()-style format to use for the - code to use for converting. - - - - The #gdouble to convert - - - - - - Determines whether a character is alphanumeric. - -Unlike the standard C library isalnum() function, this only -recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is alphabetic (i.e. a letter). - -Unlike the standard C library isalpha() function, this only -recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a control character. - -Unlike the standard C library iscntrl() function, this only -recognizes standard ASCII control characters and ignores the -locale, returning %FALSE for all non-ASCII characters. Also, -unlike the standard library function, this takes a char, not -an int, so don't call it on %EOF, but no need to cast to #guchar -before passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is digit (0-9). - -Unlike the standard C library isdigit() function, this takes -a char, not an int, so don't call it on %EOF, but no need to -cast to #guchar before passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a printing character and not a space. - -Unlike the standard C library isgraph() function, this only -recognizes standard ASCII characters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is an ASCII lower case letter. - -Unlike the standard C library islower() function, this only -recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to worry about casting -to #guchar before passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a printing character. - -Unlike the standard C library isprint() function, this only -recognizes standard ASCII characters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a punctuation character. - -Unlike the standard C library ispunct() function, this only -recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a white-space character. - -Unlike the standard C library isspace() function, this only -recognizes standard ASCII white-space and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to cast to #guchar before -passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is an ASCII upper case letter. - -Unlike the standard C library isupper() function, this only -recognizes standard ASCII letters and ignores the locale, -returning %FALSE for all non-ASCII characters. Also, unlike -the standard library function, this takes a char, not an int, -so don't call it on %EOF, but no need to worry about casting -to #guchar before passing a possibly non-ASCII character in. - - - - any character - - - - - Determines whether a character is a hexadecimal-digit character. - -Unlike the standard C library isxdigit() function, this takes -a char, not an int, so don't call it on %EOF, but no need to -cast to #guchar before passing a possibly non-ASCII character in. - - - - any character - - - - - Compare two strings, ignoring the case of ASCII characters. - -Unlike the BSD strcasecmp() function, this only recognizes standard -ASCII letters and ignores the locale, treating all non-ASCII -bytes as if they are not letters. - -This function should be used only on strings that are known to be -in encodings where the bytes corresponding to ASCII letters always -represent themselves. This includes UTF-8 and the ISO-8859-* -charsets, but not for instance double-byte encodings like the -Windows Codepage 932, where the trailing bytes of double-byte -characters include all ASCII letters. If you compare two CP932 -strings using this function, you will get false matches. - -Both @s1 and @s2 must be non-%NULL. - - - 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. - - - - - string to compare with @s2 - - - - string to compare with @s1 - - - - - - Converts all upper case ASCII letters to lower case ASCII letters. - - - a newly-allocated string, with all the upper case - characters in @str converted to lower case, with semantics that - exactly match g_ascii_tolower(). (Note that this is unlike the - old g_strdown(), which modified the string in place.) - - - - - a string - - - - length of @str in bytes, or -1 if @str is nul-terminated - - - - - - A convenience function for converting a string to a signed number. - -This function assumes that @str contains only a number of the given -@base that is within inclusive bounds limited by @min and @max. If -this is true, then the converted number is stored in @out_num. An -empty string is not a valid input. A string with leading or -trailing whitespace is also an invalid input. - -@base can be between 2 and 36 inclusive. Hexadecimal numbers must -not be prefixed with "0x" or "0X". Such a problem does not exist -for octal numbers, since they were usually prefixed with a zero -which does not change the value of the parsed number. - -Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR -domain. If the input is invalid, the error code will be -%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of -bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. - -See g_ascii_strtoll() if you have more complex needs such as -parsing a string which starts with a number, but then has other -characters. - - - %TRUE if @str was a number, otherwise %FALSE. - - - - - a string - - - - base of a parsed number - - - - a lower bound (inclusive) - - - - an upper bound (inclusive) - - - - a return location for a number - - - - - - A convenience function for converting a string to an unsigned number. - -This function assumes that @str contains only a number of the given -@base that is within inclusive bounds limited by @min and @max. If -this is true, then the converted number is stored in @out_num. An -empty string is not a valid input. A string with leading or -trailing whitespace is also an invalid input. A string with a leading sign -(`-` or `+`) is not a valid input for the unsigned parser. - -@base can be between 2 and 36 inclusive. Hexadecimal numbers must -not be prefixed with "0x" or "0X". Such a problem does not exist -for octal numbers, since they were usually prefixed with a zero -which does not change the value of the parsed number. - -Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR -domain. If the input is invalid, the error code will be -%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of -bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. - -See g_ascii_strtoull() if you have more complex needs such as -parsing a string which starts with a number, but then has other -characters. - - - %TRUE if @str was a number, otherwise %FALSE. - - - - - a string - - - - base of a parsed number - - - - a lower bound (inclusive) - - - - an upper bound (inclusive) - - - - a return location for a number - - - - - - Compare @s1 and @s2, ignoring the case of ASCII characters and any -characters after the first @n in each string. - -Unlike the BSD strcasecmp() function, this only recognizes standard -ASCII letters and ignores the locale, treating all non-ASCII -characters as if they are not letters. - -The same warning as in g_ascii_strcasecmp() applies: Use this -function only on strings known to be in encodings where bytes -corresponding to ASCII letters always represent themselves. - - - 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. - - - - - string to compare with @s2 - - - - string to compare with @s1 - - - - number of characters to compare - - - - - - Converts a string to a #gdouble value. - -This function behaves like the standard strtod() function -does in the C locale. It does this without actually changing -the current locale, since that would not be thread-safe. -A limitation of the implementation is that this function -will still accept localized versions of infinities and NANs. - -This function is typically used when reading configuration -files or other non-user input that should be locale independent. -To handle input from the user you should normally use the -locale-sensitive system strtod() function. - -To convert from a #gdouble to a string in a locale-insensitive -way, use g_ascii_dtostr(). - -If the correct value would cause overflow, plus or minus %HUGE_VAL -is returned (according to the sign of the value), and %ERANGE is -stored in %errno. If the correct value would cause underflow, -zero is returned and %ERANGE is stored in %errno. - -This function resets %errno before calling strtod() so that -you can reliably detect overflow and underflow. - - - the #gdouble value. - - - - - the string to convert to a numeric value. - - - - if non-%NULL, it returns the - character after the last character used in the conversion. - - - - - - Converts a string to a #gint64 value. -This function behaves like the standard strtoll() function -does in the C locale. It does this without actually -changing the current locale, since that would not be -thread-safe. - -This function is typically used when reading configuration -files or other non-user input that should be locale independent. -To handle input from the user you should normally use the -locale-sensitive system strtoll() function. - -If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 -is returned, and `ERANGE` is stored in `errno`. -If the base is outside the valid range, zero is returned, and -`EINVAL` is stored in `errno`. If the -string conversion fails, zero is returned, and @endptr returns @nptr -(if @endptr is non-%NULL). - - - the #gint64 value or zero on error. - - - - - the string to convert to a numeric value. - - - - if non-%NULL, it returns the - character after the last character used in the conversion. - - - - to be used for the conversion, 2..36 or 0 - - - - - - Converts a string to a #guint64 value. -This function behaves like the standard strtoull() function -does in the C locale. It does this without actually -changing the current locale, since that would not be -thread-safe. - -Note that input with a leading minus sign (`-`) is accepted, and will return -the negation of the parsed number, unless that would overflow a #guint64. -Critically, this means you cannot assume that a short fixed length input will -never result in a low return value, as the input could have a leading `-`. - -This function is typically used when reading configuration -files or other non-user input that should be locale independent. -To handle input from the user you should normally use the -locale-sensitive system strtoull() function. - -If the correct value would cause overflow, %G_MAXUINT64 -is returned, and `ERANGE` is stored in `errno`. -If the base is outside the valid range, zero is returned, and -`EINVAL` is stored in `errno`. -If the string conversion fails, zero is returned, and @endptr returns -@nptr (if @endptr is non-%NULL). - - - the #guint64 value or zero on error. - - - - - the string to convert to a numeric value. - - - - if non-%NULL, it returns the - character after the last character used in the conversion. - - - - to be used for the conversion, 2..36 or 0 - - - - - - Converts all lower case ASCII letters to upper case ASCII letters. - - - a newly allocated string, with all the lower case - characters in @str converted to upper case, with semantics that - exactly match g_ascii_toupper(). (Note that this is unlike the - old g_strup(), which modified the string in place.) - - - - - a string - - - - length of @str in bytes, or -1 if @str is nul-terminated - - - - - - Convert a character to ASCII lower case. - -Unlike the standard C library tolower() function, this only -recognizes standard ASCII letters and ignores the locale, returning -all non-ASCII characters unchanged, even if they are lower case -letters in a particular character set. Also unlike the standard -library function, this takes and returns a char, not an int, so -don't call it on %EOF but no need to worry about casting to #guchar -before passing a possibly non-ASCII character in. - - - the result of converting @c to lower case. If @c is - not an ASCII upper case letter, @c is returned unchanged. - - - - - any character - - - - - - Convert a character to ASCII upper case. - -Unlike the standard C library toupper() function, this only -recognizes standard ASCII letters and ignores the locale, returning -all non-ASCII characters unchanged, even if they are upper case -letters in a particular character set. Also unlike the standard -library function, this takes and returns a char, not an int, so -don't call it on %EOF but no need to worry about casting to #guchar -before passing a possibly non-ASCII character in. - - - the result of converting @c to upper case. If @c is not - an ASCII lower case letter, @c is returned unchanged. - - - - - any character - - - - - - Determines the numeric value of a character as a hexidecimal -digit. Differs from g_unichar_xdigit_value() because it takes -a char, so there's no worry about sign extension if characters -are signed. - - - If @c is a hex digit (according to g_ascii_isxdigit()), - its numeric value. Otherwise, -1. - - - - - an ASCII character. - - - - - - Debugging macro to terminate the application if the assertion -fails. If the assertion fails (i.e. the expression is not true), -an error message is logged and the application is terminated. - -The macro can be turned off in final releases of code by defining -`G_DISABLE_ASSERT` when compiling the application, so code must -not depend on any side effects from @expr. Similarly, it must not be used -in unit tests, otherwise the unit tests will be ineffective if compiled with -`G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests -instead. - - - - the expression to check - - - - - Debugging macro to compare two floating point numbers. - -The effect of `g_assert_cmpfloat (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - - - - a floating point number - - - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - - - another floating point number - - - - - Debugging macro to compare two floating point numbers within an epsilon. - -The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is -the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - - - - a floating point number - - - another floating point number - - - a numeric value that expresses the expected tolerance - between @n1 and @n2 - - - - - Debugging macro to compare to unsigned integers. - -This is a variant of g_assert_cmpuint() that displays the numbers -in hexadecimal notation in the message. - - - - an unsigned integer - - - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - - - another unsigned integer - - - - - Debugging macro to compare two integers. - -The effect of `g_assert_cmpint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - - - - an integer - - - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - - - another integer - - - - - Debugging macro to compare memory regions. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. - -The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is -the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @l1 and @l2. - -@m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2. - -|[<!-- language="C" --> - g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); -]| - - - - pointer to a buffer - - - length of @m1 - - - pointer to another buffer - - - length of @m2 - - - - - Debugging macro to compare two strings. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. -The strings are compared using g_strcmp0(). - -The effect of `g_assert_cmpstr (s1, op, s2)` is -the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @s1 and @s2. - -|[<!-- language="C" --> - g_assert_cmpstr (mystring, ==, "fubar"); -]| - - - - a string (may be %NULL) - - - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - - - another string (may be %NULL) - - - - - Debugging macro to compare two unsigned integers. - -The effect of `g_assert_cmpuint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. - - - - an unsigned integer - - - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - - - another unsigned integer - - - - - Debugging macro to compare two #GVariants. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. The variants are compared using -g_variant_equal(). - -The effect of `g_assert_cmpvariant (v1, v2)` is the same as -`g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is -that it can produce a message that includes the actual values of @v1 and @v2. - - - - pointer to a #GVariant - - - pointer to another #GVariant - - - - - Debugging macro to check that a method has returned -the correct #GError. - -The effect of `g_assert_error (err, dom, c)` is -the same as `g_assert_true (err != NULL && err->domain -== dom && err->code == c)`. The advantage of this -macro is that it can produce a message that includes the incorrect -error message and code. - -This can only be used to test for a specific error. If you want to -test that @err is set, but don't care what it's set to, just use -`g_assert_nonnull (err)`. - - - - a #GError, possibly %NULL - - - the expected error domain (a #GQuark) - - - the expected error code - - - - - Debugging macro to check an expression is false. - -If the assertion fails (i.e. the expression is not false), -an error message is logged and the application is either -terminated or the testcase marked as failed. - -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. - -See g_test_set_nonfatal_assertions(). - - - - the expression to check - - - - - Debugging macro to check that a #GError is not set. - -The effect of `g_assert_no_error (err)` is -the same as `g_assert_true (err == NULL)`. The advantage -of this macro is that it can produce a message that includes -the error message and code. - - - - a #GError, possibly %NULL - - - - - Debugging macro to check an expression is not %NULL. - -If the assertion fails (i.e. the expression is %NULL), -an error message is logged and the application is either -terminated or the testcase marked as failed. - -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. - -See g_test_set_nonfatal_assertions(). - - - - the expression to check - - - - - Debugging macro to check an expression is %NULL. - -If the assertion fails (i.e. the expression is not %NULL), -an error message is logged and the application is either -terminated or the testcase marked as failed. - -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. - -See g_test_set_nonfatal_assertions(). - - - - the expression to check - - - - - Debugging macro to check that an expression is true. - -If the assertion fails (i.e. the expression is not true), -an error message is logged and the application is either -terminated or the testcase marked as failed. - -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. - -See g_test_set_nonfatal_assertions(). - - - - the expression to check - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Internal function used to print messages from the public g_assert() and -g_assert_not_reached() macros. - - - - - - - log domain - - - - file containing the assertion - - - - line number of the assertion - - - - function containing the assertion - - - - expression which failed - - - - - - Specifies a function to be called at normal program termination. - -Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor -macro that maps to a call to the atexit() function in the C -library. This means that in case the code that calls g_atexit(), -i.e. atexit(), is in a DLL, the function will be called when the -DLL is detached from the program. This typically makes more sense -than that the function is called when the GLib DLL is detached, -which happened earlier when g_atexit() was a function in the GLib -DLL. - -The behaviour of atexit() in the context of dynamically loaded -modules is not formally specified and varies wildly. - -On POSIX systems, calling g_atexit() (or atexit()) in a dynamically -loaded module which is unloaded before the program terminates might -well cause a crash at program exit. - -Some POSIX systems implement atexit() like Windows, and have each -dynamically loaded module maintain an own atexit chain that is -called when the module is unloaded. - -On other POSIX systems, before a dynamically loaded module is -unloaded, the registered atexit functions (if any) residing in that -module are called, regardless where the code that registered them -resided. This is presumably the most robust approach. - -As can be seen from the above, for portability it's best to avoid -calling g_atexit() (or atexit()) except in the main executable of a -program. - It is best to avoid g_atexit(). - - - - - - - the function to call on normal program termination. - - - - - - Atomically adds @val to the value of @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic += val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - -Before version 2.30, this function did not return a value -(but g_atomic_int_exchange_and_add() did, and had the same meaning). - - - the value of @atomic before the add, signed - - - - - a pointer to a #gint or #guint - - - - the value to add - - - - - - Performs an atomic bitwise 'and' of the value of @atomic and @val, -storing the result back in @atomic. - -This call acts as a full compiler and hardware memory barrier. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic &= val; return tmp; }`. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gint or #guint - - - - the value to 'and' - - - - - - Compares @atomic to @oldval and, if equal, sets it to @newval. -If @atomic was not equal to @oldval then no change occurs. - -This compare and exchange is done atomically. - -Think of this operation as an atomic version of -`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. - -This call acts as a full compiler and hardware memory barrier. - - - %TRUE if the exchange took place - - - - - a pointer to a #gint or #guint - - - - the value to compare with - - - - the value to conditionally replace with - - - - - - Decrements the value of @atomic by 1. - -Think of this operation as an atomic version of -`{ *atomic -= 1; return (*atomic == 0); }`. - -This call acts as a full compiler and hardware memory barrier. - - - %TRUE if the resultant value is zero - - - - - a pointer to a #gint or #guint - - - - - - This function existed before g_atomic_int_add() returned the prior -value of the integer (which it now does). It is retained only for -compatibility reasons. Don't use this function in new code. - Use g_atomic_int_add() instead. - - - the value of @atomic before the add, signed - - - - - a pointer to a #gint - - - - the value to add - - - - - - Gets the current value of @atomic. - -This call acts as a full compiler and hardware -memory barrier (before the get). - - - the value of the integer - - - - - a pointer to a #gint or #guint - - - - - - Increments the value of @atomic by 1. - -Think of this operation as an atomic version of `{ *atomic += 1; }`. - -This call acts as a full compiler and hardware memory barrier. - - - - - - - a pointer to a #gint or #guint - - - - - - Performs an atomic bitwise 'or' of the value of @atomic and @val, -storing the result back in @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic |= val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gint or #guint - - - - the value to 'or' - - - - - - Sets the value of @atomic to @newval. - -This call acts as a full compiler and hardware -memory barrier (after the set). - - - - - - - a pointer to a #gint or #guint - - - - a new value to store - - - - - - Performs an atomic bitwise 'xor' of the value of @atomic and @val, -storing the result back in @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic ^= val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gint or #guint - - - - the value to 'xor' - - - - - - Atomically adds @val to the value of @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic += val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the add, signed - - - - - a pointer to a #gpointer-sized value - - - - the value to add - - - - - - Performs an atomic bitwise 'and' of the value of @atomic and @val, -storing the result back in @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic &= val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gpointer-sized value - - - - the value to 'and' - - - - - - Compares @atomic to @oldval and, if equal, sets it to @newval. -If @atomic was not equal to @oldval then no change occurs. - -This compare and exchange is done atomically. - -Think of this operation as an atomic version of -`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. - -This call acts as a full compiler and hardware memory barrier. - - - %TRUE if the exchange took place - - - - - a pointer to a #gpointer-sized value - - - - the value to compare with - - - - the value to conditionally replace with - - - - - - Gets the current value of @atomic. - -This call acts as a full compiler and hardware -memory barrier (before the get). - - - the value of the pointer - - - - - a pointer to a #gpointer-sized value - - - - - - Performs an atomic bitwise 'or' of the value of @atomic and @val, -storing the result back in @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic |= val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gpointer-sized value - - - - the value to 'or' - - - - - - Sets the value of @atomic to @newval. - -This call acts as a full compiler and hardware -memory barrier (after the set). - - - - - - - a pointer to a #gpointer-sized value - - - - a new value to store - - - - - - Performs an atomic bitwise 'xor' of the value of @atomic and @val, -storing the result back in @atomic. - -Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic ^= val; return tmp; }`. - -This call acts as a full compiler and hardware memory barrier. - - - the value of @atomic before the operation, unsigned - - - - - a pointer to a #gpointer-sized value - - - - the value to 'xor' - - - - - - Atomically acquires a reference on the data pointed by @mem_block. - - - a pointer to the data, - with its reference count increased - - - - - a pointer to reference counted data - - - - - - Allocates @block_size bytes of memory, and adds atomic -reference counting semantics to it. - -The data will be freed when its reference count drops to -zero. - -The allocated data is guaranteed to be suitably aligned for any -built-in type. - - - a pointer to the allocated memory - - - - - the size of the allocation, must be greater than 0 - - - - - - Allocates @block_size bytes of memory, and adds atomic -referenc counting semantics to it. - -The contents of the returned data is set to zero. - -The data will be freed when its reference count drops to -zero. - -The allocated data is guaranteed to be suitably aligned for any -built-in type. - - - a pointer to the allocated memory - - - - - the size of the allocation, must be greater than 0 - - - - - - Allocates a new block of data with atomic reference counting -semantics, and copies @block_size bytes of @mem_block -into it. - - - a pointer to the allocated - memory - - - - - the number of bytes to copy, must be greater than 0 - - - - the memory to copy - - - - - - Retrieves the size of the reference counted data pointed by @mem_block. - - - the size of the data, in bytes - - - - - a pointer to reference counted data - - - - - - A convenience macro to allocate atomically reference counted -data with the size of the given @type. - -This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and -casts the returned pointer to a pointer of the given @type, -avoiding a type cast in the source code. - - - - the type to allocate, typically a structure name - - - - - A convenience macro to allocate atomically reference counted -data with the size of the given @type, and set its contents -to zero. - -This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and -casts the returned pointer to a pointer of the given @type, -avoiding a type cast in the source code. - - - - the type to allocate, typically a structure name - - - - - Atomically releases a reference on the data pointed by @mem_block. - -If the reference was the last one, it will free the -resources allocated for @mem_block. - - - - - - - a pointer to reference counted data - - - - - - Atomically releases a reference on the data pointed by @mem_block. - -If the reference was the last one, it will call @clear_func -to clear the contents of @mem_block, and then will free the -resources allocated for @mem_block. - - - - - - - a pointer to reference counted data - - - - a function to call when clearing the data - - - - - - Atomically compares the current value of @arc with @val. - - - %TRUE if the reference count is the same - as the given value - - - - - the address of an atomic reference count variable - - - - the value to compare - - - - - - Atomically decreases the reference count. - - - %TRUE if the reference count reached 0, and %FALSE otherwise - - - - - the address of an atomic reference count variable - - - - - - Atomically increases the reference count. - - - - - - - the address of an atomic reference count variable - - - - - - Initializes a reference count variable. - - - - - - - the address of an atomic reference count variable - - - - - - Decode a sequence of Base-64 encoded text into binary data. Note -that the returned binary data is not necessarily zero-terminated, -so it should not be used as a character string. - - - - newly allocated buffer containing the binary data - that @text represents. The returned buffer must - be freed with g_free(). - - - - - - - zero-terminated string with base64 text to decode - - - - The length of the decoded data is written here - - - - - - Decode a sequence of Base-64 encoded text into binary data -by overwriting the input data. - - - The binary data that @text responds. This pointer - is the same as the input @text. - - - - - zero-terminated - string with base64 text to decode - - - - - - The length of the decoded data is written here - - - - - - Incrementally decode a sequence of binary data from its Base-64 stringified -representation. By calling this function multiple times you can convert -data in chunks to avoid having to have the full encoded data in memory. - -The output buffer must be large enough to fit all the data that will -be written to it. Since base64 encodes 3 bytes in 4 chars you need -at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero -state). - - - The number of bytes of output that was written - - - - - binary input data - - - - - - max length of @in data to decode - - - - output buffer - - - - - - Saved state between steps, initialize to 0 - - - - Saved state between steps, initialize to 0 - - - - - - Encode a sequence of binary data into its Base-64 stringified -representation. - - - a newly allocated, zero-terminated Base-64 - encoded string representing @data. The returned string must - be freed with g_free(). - - - - - the binary data to encode - - - - - - the length of @data - - - - - - Flush the status from a sequence of calls to g_base64_encode_step(). - -The output buffer must be large enough to fit all the data that will -be written to it. It will need up to 4 bytes, or up to 5 bytes if -line-breaking is enabled. - -The @out array will not be automatically nul-terminated. - - - The number of bytes of output that was written - - - - - whether to break long lines - - - - pointer to destination buffer - - - - - - Saved state from g_base64_encode_step() - - - - Saved state from g_base64_encode_step() - - - - - - Incrementally encode a sequence of binary data into its Base-64 stringified -representation. By calling this function multiple times you can convert -data in chunks to avoid having to have the full encoded data in memory. - -When all of the data has been converted you must call -g_base64_encode_close() to flush the saved state. - -The output buffer must be large enough to fit all the data that will -be written to it. Due to the way base64 encodes you will need -at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of -non-zero state). If you enable line-breaking you will need at least: -((@len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space. - -@break_lines is typically used when putting base64-encoded data in emails. -It breaks the lines at 76 columns instead of putting all of the text on -the same line. This avoids problems with long lines in the email system. -Note however that it breaks the lines with `LF` characters, not -`CR LF` sequences, so the result cannot be passed directly to SMTP -or certain other protocols. - - - The number of bytes of output that was written - - - - - the binary data to encode - - - - - - the length of @in - - - - whether to break long lines - - - - pointer to destination buffer - - - - - - Saved state between steps, initialize to 0 - - - - Saved state between steps, initialize to 0 - - - - - - Gets the name of the file without any leading directory -components. It returns a pointer into the given file name -string. - Use g_path_get_basename() instead, but notice - that g_path_get_basename() allocates new memory for the - returned string, unlike this function which returns a pointer - into the argument. - - - the name of the file without any leading - directory components - - - - - the name of the file - - - - - - Sets the indicated @lock_bit in @address. If the bit is already -set, this call will block until g_bit_unlock() unsets the -corresponding bit. - -Attempting to lock on two different bits within the same integer is -not supported and will very probably cause deadlocks. - -The value of the bit that is set is (1u << @bit). If @bit is not -between 0 and 31 then the result is undefined. - -This function accesses @address atomically. All other accesses to -@address must be atomic in order for this function to work -reliably. - - - - - - - a pointer to an integer - - - - a bit value between 0 and 31 - - - - - - Find the position of the first bit set in @mask, searching -from (but not including) @nth_bit upwards. Bits are numbered -from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, -usually). To start searching from the 0th bit, set @nth_bit to -1. - - - the index of the first bit set which is higher than @nth_bit, or -1 - if no higher bits are set - - - - - a #gulong containing flags - - - - the index of the bit to start the search from - - - - - - Find the position of the first bit set in @mask, searching -from (but not including) @nth_bit downwards. Bits are numbered -from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, -usually). To start searching from the last bit, set @nth_bit to --1 or GLIB_SIZEOF_LONG * 8. - - - the index of the first bit set which is lower than @nth_bit, or -1 - if no lower bits are set - - - - - a #gulong containing flags - - - - the index of the bit to start the search from - - - - - - Gets the number of bits used to hold @number, -e.g. if @number is 4, 3 bits are needed. - - - the number of bits used to hold @number - - - - - a #guint - - - - - - Sets the indicated @lock_bit in @address, returning %TRUE if -successful. If the bit is already set, returns %FALSE immediately. - -Attempting to lock on two different bits within the same integer is -not supported. - -The value of the bit that is set is (1u << @bit). If @bit is not -between 0 and 31 then the result is undefined. - -This function accesses @address atomically. All other accesses to -@address must be atomic in order for this function to work -reliably. - - - %TRUE if the lock was acquired - - - - - a pointer to an integer - - - - a bit value between 0 and 31 - - - - - - Clears the indicated @lock_bit in @address. If another thread is -currently blocked in g_bit_lock() on this same bit then it will be -woken up. - -This function accesses @address atomically. All other accesses to -@address must be atomic in order for this function to work -reliably. - - - - - - - a pointer to an integer - - - - a bit value between 0 and 31 - - - - - - - - - - - Creates a filename from a series of elements using the correct -separator for filenames. - -On Unix, this function behaves identically to `g_build_path -(G_DIR_SEPARATOR_S, first_element, ....)`. - -On Windows, it takes into account that either the backslash -(`\` or slash (`/`) can be used as separator in filenames, but -otherwise behaves as on UNIX. When file pathname separators need -to be inserted, the one that last previously occurred in the -parameters (reading from left to right) is used. - -No attempt is made to force the resulting filename to be an absolute -path. If the first element is a relative path, the result will -be a relative path. - - - a newly-allocated string that must be freed with - g_free(). - - - - - the first element in the path - - - - remaining elements in path, terminated by %NULL - - - - - - Behaves exactly like g_build_filename(), but takes the path elements -as a va_list. This function is mainly meant for language bindings. - - - a newly-allocated string that must be freed - with g_free(). - - - - - the first element in the path - - - - va_list of remaining elements in path - - - - - - Behaves exactly like g_build_filename(), but takes the path elements -as a string array, instead of varargs. This function is mainly -meant for language bindings. - - - a newly-allocated string that must be freed - with g_free(). - - - - - %NULL-terminated - array of strings containing the path elements. - - - - - - - - Creates a path from a series of elements using @separator as the -separator between elements. At the boundary between two elements, -any trailing occurrences of separator in the first element, or -leading occurrences of separator in the second element are removed -and exactly one copy of the separator is inserted. - -Empty elements are ignored. - -The number of leading copies of the separator on the result is -the same as the number of leading copies of the separator on -the first non-empty element. - -The number of trailing copies of the separator on the result is -the same as the number of trailing copies of the separator on -the last non-empty element. (Determination of the number of -trailing copies is done without stripping leading copies, so -if the separator is `ABA`, then `ABABA` has 1 trailing copy.) - -However, if there is only a single non-empty element, and there -are no characters in that element not part of the leading or -trailing separators, then the result is exactly the original value -of that element. - -Other than for determination of the number of leading and trailing -copies of the separator, elements consisting only of copies -of the separator are ignored. - - - a newly-allocated string that must be freed with - g_free(). - - - - - a string used to separator the elements of the path. - - - - the first element in the path - - - - remaining elements in path, terminated by %NULL - - - - - - Behaves exactly like g_build_path(), but takes the path elements -as a string array, instead of varargs. This function is mainly -meant for language bindings. - - - a newly-allocated string that must be freed - with g_free(). - - - - - a string used to separator the elements of the path. - - - - %NULL-terminated - array of strings containing the path elements. - - - - - - - - Frees the memory allocated by the #GByteArray. If @free_segment is -%TRUE it frees the actual byte data. If the reference count of -@array is greater than one, the #GByteArray wrapper is preserved but -the size of @array will be set to zero. - - - the element data if @free_segment is %FALSE, otherwise - %NULL. The element data should be freed using g_free(). - - - - - a #GByteArray - - - - - - if %TRUE the actual byte data is freed as well - - - - - - Transfers the data from the #GByteArray into a new immutable #GBytes. - -The #GByteArray is freed unless the reference count of @array is greater -than one, the #GByteArray wrapper is preserved but the size of @array -will be set to zero. - -This is identical to using g_bytes_new_take() and g_byte_array_free() -together. - - - a new immutable #GBytes representing same - byte data that was in the array - - - - - a #GByteArray - - - - - - - - Creates a new #GByteArray with a reference count of 1. - - - the new #GByteArray - - - - - - - Create byte array containing the data. The data will be owned by the array -and will be freed with g_free(), i.e. it could be allocated using g_strdup(). - - - a new #GByteArray - - - - - - - byte data for the array - - - - - - length of @data - - - - - - Frees the data in the array and resets the size to zero, while -the underlying array is preserved for use elsewhere and returned -to the caller. - - - the element data, which should be - freed using g_free(). - - - - - a #GByteArray. - - - - - - pointer to retrieve the number of - elements of the original array - - - - - - Atomically decrements the reference count of @array by one. If the -reference count drops to 0, all memory allocated by the array is -released. This function is thread-safe and may be called from any -thread. - - - - - - - A #GByteArray - - - - - - - - Gets the canonical file name from @filename. All triple slashes are turned into -single slashes, and all `..` and `.`s resolved against @relative_to. - -Symlinks are not followed, and the returned path is guaranteed to be absolute. - -If @filename is an absolute path, @relative_to is ignored. Otherwise, -@relative_to will be prepended to @filename to make it absolute. @relative_to -must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback -to g_get_current_dir(). - -This function never fails, and will canonicalize file paths even if they don't -exist. - -No file system I/O is done. - - - a newly allocated string with the -canonical file path - - - - - the name of the file - - - - the relative directory, or %NULL -to use the current working directory - - - - - - A wrapper for the POSIX chdir() function. The function changes the -current directory of the process to @path. - -See your C library manual for more details about chdir(). - - - 0 on success, -1 if an error occurred. - - - - - a pathname in the GLib file name encoding - (UTF-8 on Windows) - - - - - - Checks that the GLib library in use is compatible with the -given version. Generally you would pass in the constants -#GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION -as the three arguments to this function; that produces -a check that the library in use is compatible with -the version of GLib the application or module was compiled -against. - -Compatibility is defined by two things: first the version -of the running library is newer than the version -@required_major.required_minor.@required_micro. Second -the running library must be binary compatible with the -version @required_major.required_minor.@required_micro -(same major version.) - - - %NULL if the GLib library is compatible with the - given version, or a string describing the version mismatch. - The returned string is owned by GLib and must not be modified - or freed. - - - - - the required major version - - - - the required minor version - - - - the required micro version - - - - - - Gets the length in bytes of digests of type @checksum_type - - - the checksum length, or -1 if @checksum_type is -not supported. - - - - - a #GChecksumType - - - - - - Sets a function to be called when the child indicated by @pid -exits, at a default priority, #G_PRIORITY_DEFAULT. - -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. - -Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the -source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. - -GLib supports only a single callback per process id. -On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. - -This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you -need greater control. - - - the ID (greater than 0) of the event source. - - - - - process id to watch. On POSIX the positive pid of a child -process. On Windows a handle for a process (which doesn't have to be -a child). - - - - function to call - - - - data to pass to @function - - - - - - Sets a function to be called when the child indicated by @pid -exits, at the priority @priority. - -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. - -In many programs, you will want to call g_spawn_check_exit_status() -in the callback to determine whether or not the child exited -successfully. - -Also, note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the source -is still active. Typically, you should invoke g_spawn_close_pid() -in the callback function for the source. - -GLib supports only a single callback per process id. -On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. - -This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you -need greater control. - - - the ID (greater than 0) of the event source. - - - - - the priority of the idle source. Typically this will be in the - range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - - - - process to watch. On POSIX the positive pid of a child process. On -Windows a handle for a process (which doesn't have to be a child). - - - - function to call - - - - data to pass to @function - - - - function to call when the idle is removed, or %NULL - - - - - - Creates a new child_watch source. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. - -Note that child watch sources can only be used in conjunction with -`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. - -Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the -source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. - -On POSIX platforms, the following restrictions apply to this API -due to limitations in POSIX process interfaces: - -* @pid must be a child of this process -* @pid must be positive -* the application must not call `waitpid` with a non-positive - first argument, for instance in another thread -* the application must not wait for @pid to exit by any other - mechanism, including `waitpid(pid, ...)` or a second child-watch - source for the same @pid -* the application must not ignore SIGCHILD - -If any of those conditions are not met, this and related APIs will -not work correctly. This can often be diagnosed via a GLib warning -stating that `ECHILD` was received by `waitpid`. - -Calling `waitpid` for specific processes other than @pid remains a -valid thing to do. - - - the newly-created child watch source - - - - - process to watch. On POSIX the positive pid of a child process. On -Windows a handle for a process (which doesn't have to be a child). - - - - - - If @err or *@err is %NULL, does nothing. Otherwise, -calls g_error_free() on *@err and sets *@err to %NULL. - - - - - - - Clears a numeric handler, such as a #GSource ID. - -@tag_ptr must be a valid pointer to the variable holding the handler. - -If the ID is zero then this function does nothing. -Otherwise, clear_func() is called with the ID as a parameter, and the tag is -set to zero. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - a pointer to the handler ID - - - - the function to call to clear the handler - - - - - - Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy. - -@list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing. - - - - - - - a #GList return location - - - - - - the function to pass to g_list_free_full() or %NULL to not free elements - - - - - - Clears a reference to a variable. - -@pp must not be %NULL. - -If the reference is %NULL then this function does nothing. -Otherwise, the variable is destroyed using @destroy and the -pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. This will mask any warnings about incompatible function types -or calling conventions, so you must ensure that your @destroy function is -compatible with being called as `GDestroyNotify` using the standard calling -convention for the platform that GLib was compiled for; otherwise the program -will experience undefined behaviour. - - - - - - - a pointer to a variable, struct member etc. holding a - pointer - - - - a function to which a gpointer can be passed, to destroy *@pp - - - - - - Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy. - -@slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing. - - - - - - - a #GSList return location - - - - - - the function to pass to g_slist_free_full() or %NULL to not free elements - - - - - - This wraps the close() call; in case of error, %errno will be -preserved, but the error will also be stored as a #GError in @error. - -Besides using #GError, there is another major reason to prefer this -function over the call provided by the system; on Unix, it will -attempt to correctly handle %EINTR, which has platform-specific -semantics. - - - %TRUE on success, %FALSE if there was an error. - - - - - A file descriptor - - - - - - Computes the checksum for a binary @data. This is a -convenience wrapper for g_checksum_new(), g_checksum_get_string() -and g_checksum_free(). - -The hexadecimal string returned will be in lower case. - - - the digest of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. - - - - - a #GChecksumType - - - - binary blob to compute the digest of - - - - - - Computes the checksum for a binary @data of @length. This is a -convenience wrapper for g_checksum_new(), g_checksum_get_string() -and g_checksum_free(). - -The hexadecimal string returned will be in lower case. - - - the digest of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. - - - - - a #GChecksumType - - - - binary blob to compute the digest of - - - - - - length of @data - - - - - - Computes the checksum of a string. - -The hexadecimal string returned will be in lower case. - - - the checksum as a hexadecimal string. The returned string - should be freed with g_free() when done using it. - - - - - a #GChecksumType - - - - the string to compute the checksum of - - - - the length of the string, or -1 if the string is null-terminated. - - - - - - Computes the HMAC for a binary @data. This is a -convenience wrapper for g_hmac_new(), g_hmac_get_string() -and g_hmac_unref(). - -The hexadecimal string returned will be in lower case. - - - the HMAC of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. - - - - - a #GChecksumType to use for the HMAC - - - - the key to use in the HMAC - - - - binary blob to compute the HMAC of - - - - - - Computes the HMAC for a binary @data of @length. This is a -convenience wrapper for g_hmac_new(), g_hmac_get_string() -and g_hmac_unref(). - -The hexadecimal string returned will be in lower case. - - - the HMAC of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. - - - - - a #GChecksumType to use for the HMAC - - - - the key to use in the HMAC - - - - - - the length of the key - - - - binary blob to compute the HMAC of - - - - - - length of @data - - - - - - Computes the HMAC for a string. - -The hexadecimal string returned will be in lower case. - - - the HMAC as a hexadecimal string. - The returned string should be freed with g_free() - when done using it. - - - - - a #GChecksumType to use for the HMAC - - - - the key to use in the HMAC - - - - - - the length of the key - - - - the string to compute the HMAC for - - - - the length of the string, or -1 if the string is nul-terminated - - - - - - Converts a string from one character set to another. - -Note that you should use g_iconv() for streaming conversions. -Despite the fact that @bytes_read can return information about partial -characters, the g_convert_... functions are not generally suitable -for streaming. If the underlying converter maintains internal state, -then this won't be preserved across successive calls to g_convert(), -g_convert_with_iconv() or g_convert_with_fallback(). (An example of -this is the GNU C converter for CP1255 which does not emit a base -character until it knows that the next character is not a mark that -could combine with the base character.) - -Using extensions such as "//TRANSLIT" may not work (or may not work -well) on many platforms. Consider using g_str_to_ascii() instead. - - - - If the conversion was successful, a newly allocated buffer - containing the converted string, which must be freed with g_free(). - Otherwise %NULL and @error will be set. - - - - - - - - the string to convert. - - - - - - the length of the string in bytes, or -1 if the string is - nul-terminated (Note that some encodings may allow nul - bytes to occur inside strings. In that case, using -1 - for the @len parameter is unsafe) - - - - name of character set into which to convert @str - - - - character set of @str. - - - - location to store the number of bytes in - the input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in - the output buffer (not including the terminating nul). - - - - - - - - - - - Converts a string from one character set to another, possibly -including fallback sequences for characters not representable -in the output. Note that it is not guaranteed that the specification -for the fallback sequences in @fallback will be honored. Some -systems may do an approximate conversion from @from_codeset -to @to_codeset in their iconv() functions, -in which case GLib will simply return that approximate conversion. - -Note that you should use g_iconv() for streaming conversions. -Despite the fact that @bytes_read can return information about partial -characters, the g_convert_... functions are not generally suitable -for streaming. If the underlying converter maintains internal state, -then this won't be preserved across successive calls to g_convert(), -g_convert_with_iconv() or g_convert_with_fallback(). (An example of -this is the GNU C converter for CP1255 which does not emit a base -character until it knows that the next character is not a mark that -could combine with the base character.) - - - - If the conversion was successful, a newly allocated buffer - containing the converted string, which must be freed with g_free(). - Otherwise %NULL and @error will be set. - - - - - - - - the string to convert. - - - - - - the length of the string in bytes, or -1 if the string is - nul-terminated (Note that some encodings may allow nul - bytes to occur inside strings. In that case, using -1 - for the @len parameter is unsafe) - - - - name of character set into which to convert @str - - - - character set of @str. - - - - UTF-8 string to use in place of characters not - present in the target encoding. (The string must be - representable in the target encoding). - If %NULL, characters not in the target encoding will - be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. - - - - location to store the number of bytes in - the input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. - - - - the number of bytes stored in - the output buffer (not including the terminating nul). - - - - - - Converts a string from one character set to another. - -Note that you should use g_iconv() for streaming conversions. -Despite the fact that @bytes_read can return information about partial -characters, the g_convert_... functions are not generally suitable -for streaming. If the underlying converter maintains internal state, -then this won't be preserved across successive calls to g_convert(), -g_convert_with_iconv() or g_convert_with_fallback(). (An example of -this is the GNU C converter for CP1255 which does not emit a base -character until it knows that the next character is not a mark that -could combine with the base character.) - -Characters which are valid in the input character set, but which have no -representation in the output character set will result in a -%G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv() -specification, which leaves this behaviour implementation defined. Note that -this is the same error code as is returned for an invalid byte sequence in -the input character set. To get defined behaviour for conversion of -unrepresentable characters, use g_convert_with_fallback(). - - - - If the conversion was successful, a newly allocated buffer - containing the converted string, which must be freed with - g_free(). Otherwise %NULL and @error will be set. - - - - - - - - the string to convert. - - - - - - the length of the string in bytes, or -1 if the string is - nul-terminated (Note that some encodings may allow nul - bytes to occur inside strings. In that case, using -1 - for the @len parameter is unsafe) - - - - conversion descriptor from g_iconv_open() - - - - location to store the number of bytes in - the input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in - the output buffer (not including the terminating nul). - - - - - - Frees all the data elements of the datalist. -The data elements' destroy functions are called -if they have been set. - - - - - - - a datalist. - - - - - - Calls the given function for each data element of the datalist. The -function is called with each data element's #GQuark id and data, -together with the given @user_data parameter. Note that this -function is NOT thread-safe. So unless @datalist can be protected -from any modifications during invocation of this function, it should -not be called. - -@func can make changes to @datalist, but the iteration will not -reflect changes made during the g_datalist_foreach() call, other -than skipping over elements that are removed. - - - - - - - a datalist. - - - - the function to call for each data element. - - - - user data to pass to the function. - - - - - - Gets a data element, using its string identifier. This is slower than -g_datalist_id_get_data() because it compares strings. - - - the data element, or %NULL if it - is not found. - - - - - a datalist. - - - - the string identifying a data element. - - - - - - Gets flags values packed in together with the datalist. -See g_datalist_set_flags(). - - - the flags of the datalist - - - - - pointer to the location that holds a list - - - - - - This is a variant of g_datalist_id_get_data() which -returns a 'duplicate' of the value. @dup_func defines the -meaning of 'duplicate' in this context, it could e.g. -take a reference on a ref-counted object. - -If the @key_id is not set in the datalist then @dup_func -will be called with a %NULL argument. - -Note that @dup_func is called while the datalist is locked, so it -is not allowed to read or modify the datalist. - -This function can be useful to avoid races when multiple -threads are using the same datalist and the same key. - - - the result of calling @dup_func on the value - associated with @key_id in @datalist, or %NULL if not set. - If @dup_func is %NULL, the value is returned unmodified. - - - - - location of a datalist - - - - the #GQuark identifying a data element - - - - function to duplicate the old value - - - - passed as user_data to @dup_func - - - - - - Retrieves the data element corresponding to @key_id. - - - the data element, or %NULL if - it is not found. - - - - - a datalist. - - - - the #GQuark identifying a data element. - - - - - - Removes an element, using its #GQuark identifier. - - - - a datalist. - - - the #GQuark identifying the data element. - - - - - Removes an element, without calling its destroy notification -function. - - - the data previously stored at @key_id, - or %NULL if none. - - - - - a datalist. - - - - the #GQuark identifying a data element. - - - - - - Compares the member that is associated with @key_id in -@datalist to @oldval, and if they are the same, replace -@oldval with @newval. - -This is like a typical atomic compare-and-exchange -operation, for a member of @datalist. - -If the previous value was replaced then ownership of the -old value (@oldval) is passed to the caller, including -the registered destroy notify for it (passed out in @old_destroy). -Its up to the caller to free this as he wishes, which may -or may not include using @old_destroy as sometimes replacement -should not destroy the object in the normal way. - - - %TRUE if the existing value for @key_id was replaced - by @newval, %FALSE otherwise. - - - - - location of a datalist - - - - the #GQuark identifying a data element - - - - the old value to compare against - - - - the new value to replace it with - - - - destroy notify for the new value - - - - destroy notify for the existing value - - - - - - Sets the data corresponding to the given #GQuark id. Any previous -data with the same key is removed, and its destroy function is -called. - - - - a datalist. - - - the #GQuark to identify the data element. - - - the data element, or %NULL to remove any previous element - corresponding to @q. - - - - - Sets the data corresponding to the given #GQuark id, and the -function to be called when the element is removed from the datalist. -Any previous data with the same key is removed, and its destroy -function is called. - - - - - - - a datalist. - - - - the #GQuark to identify the data element. - - - - the data element or %NULL to remove any previous element - corresponding to @key_id. - - - - the function to call when the data element is - removed. This function will be called with the data - element and can be used to free any memory allocated - for it. If @data is %NULL, then @destroy_func must - also be %NULL. - - - - - - Resets the datalist to %NULL. It does not free any memory or call -any destroy functions. - - - - - - - a pointer to a pointer to a datalist. - - - - - - Removes an element using its string identifier. The data element's -destroy function is called if it has been set. - - - - a datalist. - - - the string identifying the data element. - - - - - Removes an element, without calling its destroy notifier. - - - - a datalist. - - - the string identifying the data element. - - - - - Sets the data element corresponding to the given string identifier. - - - - a datalist. - - - the string to identify the data element. - - - the data element, or %NULL to remove any previous element - corresponding to @k. - - - - - Sets the data element corresponding to the given string identifier, -and the function to be called when the data element is removed. - - - - a datalist. - - - the string to identify the data element. - - - the data element, or %NULL to remove any previous element - corresponding to @k. - - - the function to call when the data element is removed. - This function will be called with the data element and can be used to - free any memory allocated for it. If @d is %NULL, then @f must - also be %NULL. - - - - - Turns on flag values for a data list. This function is used -to keep a small number of boolean flags in an object with -a data list without using any additional space. It is -not generally useful except in circumstances where space -is very tight. (It is used in the base #GObject type, for -example.) - - - - - - - pointer to the location that holds a list - - - - the flags to turn on. The values of the flags are - restricted by %G_DATALIST_FLAGS_MASK (currently - 3; giving two possible boolean flags). - A value for @flags that doesn't fit within the mask is - an error. - - - - - - Turns off flag values for a data list. See g_datalist_unset_flags() - - - - - - - pointer to the location that holds a list - - - - the flags to turn off. The values of the flags are - restricted by %G_DATALIST_FLAGS_MASK (currently - 3: giving two possible boolean flags). - A value for @flags that doesn't fit within the mask is - an error. - - - - - - Destroys the dataset, freeing all memory allocated, and calling any -destroy functions set for data elements. - - - - - - - the location identifying the dataset. - - - - - - Calls the given function for each data element which is associated -with the given location. Note that this function is NOT thread-safe. -So unless @dataset_location can be protected from any modifications -during invocation of this function, it should not be called. - -@func can make changes to the dataset, but the iteration will not -reflect changes made during the g_dataset_foreach() call, other -than skipping over elements that are removed. - - - - - - - the location identifying the dataset. - - - - the function to call for each data element. - - - - user data to pass to the function. - - - - - - Gets the data element corresponding to a string. - - - - the location identifying the dataset. - - - the string identifying the data element. - - - - - Gets the data element corresponding to a #GQuark. - - - the data element corresponding to - the #GQuark, or %NULL if it is not found. - - - - - the location identifying the dataset. - - - - the #GQuark id to identify the data element. - - - - - - Removes a data element from a dataset. The data element's destroy -function is called if it has been set. - - - - the location identifying the dataset. - - - the #GQuark id identifying the data element. - - - - - Removes an element, without calling its destroy notification -function. - - - the data previously stored at @key_id, - or %NULL if none. - - - - - the location identifying the dataset. - - - - the #GQuark ID identifying the data element. - - - - - - Sets the data element associated with the given #GQuark id. Any -previous data with the same key is removed, and its destroy function -is called. - - - - the location identifying the dataset. - - - the #GQuark id to identify the data element. - - - the data element. - - - - - Sets the data element associated with the given #GQuark id, and also -the function to call when the data element is destroyed. Any -previous data with the same key is removed, and its destroy function -is called. - - - - - - - the location identifying the dataset. - - - - the #GQuark id to identify the data element. - - - - the data element. - - - - the function to call when the data element is - removed. This function will be called with the data - element and can be used to free any memory allocated - for it. - - - - - - Removes a data element corresponding to a string. Its destroy -function is called if it has been set. - - - - the location identifying the dataset. - - - the string identifying the data element. - - - - - Removes an element, without calling its destroy notifier. - - - - the location identifying the dataset. - - - the string identifying the data element. - - - - - Sets the data corresponding to the given string identifier. - - - - the location identifying the dataset. - - - the string to identify the data element. - - - the data element. - - - - - Sets the data corresponding to the given string identifier, and the -function to call when the data element is destroyed. - - - - the location identifying the dataset. - - - the string to identify the data element. - - - the data element. - - - the function to call when the data element is removed. This - function will be called with the data element and can be used to - free any memory allocated for it. - - - - - Returns the number of days in a month, taking leap -years into account. - - - number of days in @month during the @year - - - - - month - - - - year - - - - - - Returns the number of weeks in the year, where weeks -are taken to start on Monday. Will be 52 or 53. The -date must be valid. (Years always have 52 7-day periods, -plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many -Mondays are in the year, i.e. there are 53 Mondays if -one of the extra days happens to be a Monday.) - - - number of Mondays in the year - - - - - a year - - - - - - Returns the number of weeks in the year, where weeks -are taken to start on Sunday. Will be 52 or 53. The -date must be valid. (Years always have 52 7-day periods, -plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many -Sundays are in the year, i.e. there are 53 Sundays if -one of the extra days happens to be a Sunday.) - - - the number of weeks in @year - - - - - year to count weeks in - - - - - - Returns %TRUE if the year is a leap year. - -For the purposes of this function, leap year is every year -divisible by 4 unless that year is divisible by 100. If it -is divisible by 100 it would be a leap year only if that year -is also divisible by 400. - - - %TRUE if the year is a leap year - - - - - year to check - - - - - - Generates a printed representation of the date, in a -[locale][setlocale]-specific way. -Works just like the platform's C library strftime() function, -but only accepts date-related formats; time-related formats -give undefined results. Date must be valid. Unlike strftime() -(which uses the locale encoding), works on a UTF-8 format -string and stores a UTF-8 result. - -This function does not provide any conversion specifiers in -addition to those implemented by the platform's C library. -For example, don't expect that using g_date_strftime() would -make the \%F provided by the C99 strftime() work on Windows -where the C library only complies to C89. - - - number of characters written to the buffer, or 0 the buffer was too small - - - - - destination buffer - - - - buffer size - - - - format string - - - - valid #GDate - - - - - - A comparison function for #GDateTimes that is suitable -as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - - - -1, 0 or 1 if @dt1 is less than, equal to or greater - than @dt2. - - - - - first #GDateTime to compare - - - - second #GDateTime to compare - - - - - - Checks to see if @dt1 and @dt2 are equal. - -Equal here means that they represent the same moment after converting -them to the same time zone. - - - %TRUE if @dt1 and @dt2 are equal - - - - - a #GDateTime - - - - a #GDateTime - - - - - - Hashes @datetime into a #guint, suitable for use within #GHashTable. - - - a #guint containing the hash - - - - - a #GDateTime - - - - - - Returns %TRUE if the day of the month is valid (a day is valid if it's -between 1 and 31 inclusive). - - - %TRUE if the day is valid - - - - - day to check - - - - - - Returns %TRUE if the day-month-year triplet forms a valid, existing day -in the range of days #GDate understands (Year 1 or later, no more than -a few thousand years in the future). - - - %TRUE if the date is a valid one - - - - - day - - - - month - - - - year - - - - - - Returns %TRUE if the Julian day is valid. Anything greater than zero -is basically a valid Julian, though there is a 32-bit limit. - - - %TRUE if the Julian day is valid - - - - - Julian day to check - - - - - - Returns %TRUE if the month value is valid. The 12 #GDateMonth -enumeration values are the only valid months. - - - %TRUE if the month is valid - - - - - month - - - - - - Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration -values are the only valid weekdays. - - - %TRUE if the weekday is valid - - - - - weekday - - - - - - Returns %TRUE if the year is valid. Any year greater than 0 is valid, -though there is a 16-bit limit to what #GDate will understand. - - - %TRUE if the year is valid - - - - - year - - - - - - This is a variant of g_dgettext() that allows specifying a locale -category instead of always using `LC_MESSAGES`. See g_dgettext() for -more information about how this functions differs from calling -dcgettext() directly. - - - the translated string for the given locale category - - - - - the translation domain to use, or %NULL to use - the domain set with textdomain() - - - - message to translate - - - - a locale category - - - - - - This function is a wrapper of dgettext() which does not translate -the message if the default domain as set with textdomain() has no -translations for the current locale. - -The advantage of using this function over dgettext() proper is that -libraries using this function (like GTK+) will not use translations -if the application using the library does not have translations for -the current locale. This results in a consistent English-only -interface instead of one having partial translations. For this -feature to work, the call to textdomain() and setlocale() should -precede any g_dgettext() invocations. For GTK+, it means calling -textdomain() before gtk_init or its variants. - -This function disables translations if and only if upon its first -call all the following conditions hold: - -- @domain is not %NULL - -- textdomain() has been called to set a default text domain - -- there is no translations available for the default text domain - and the current locale - -- current locale is not "C" or any English locales (those - starting with "en_") - -Note that this behavior may not be desired for example if an application -has its untranslated messages in a language other than English. In those -cases the application should call textdomain() after initializing GTK+. - -Applications should normally not use this function directly, -but use the _() macro for translations. - - - The translated string - - - - - the translation domain to use, or %NULL to use - the domain set with textdomain() - - - - message to translate - - - - - - Creates a subdirectory in the preferred directory for temporary -files (as returned by g_get_tmp_dir()). - -@tmpl should be a string in the GLib file name encoding containing -a sequence of six 'X' characters, as the parameter to g_mkstemp(). -However, unlike these functions, the template should only be a -basename, no directory components are allowed. If template is -%NULL, a default template is used. - -Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not -modified, and might thus be a read-only literal string. - - - The actual name used. This string - should be freed with g_free() when not needed any longer and is - is in the GLib file name encoding. In case of errors, %NULL is - returned and @error will be set. - - - - - Template for directory name, - as in g_mkdtemp(), basename only, or %NULL for a default template - - - - - - Compares two #gpointer arguments and returns %TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using opaque pointers compared by pointer value as -keys in a #GHashTable. - -This equality function is also appropriate for keys that are integers -stored in pointers, such as `GINT_TO_POINTER (n)`. - - - %TRUE if the two keys match. - - - - - a key - - - - a key to compare with @v1 - - - - - - Converts a gpointer to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, -when using opaque pointers compared by pointer value as keys in a -#GHashTable. - -This hash function is also appropriate for keys that are integers -stored in pointers, such as `GINT_TO_POINTER (n)`. - - - a hash value corresponding to the key. - - - - - a #gpointer key - - - - - - This function is a wrapper of dngettext() which does not translate -the message if the default domain as set with textdomain() has no -translations for the current locale. - -See g_dgettext() for details of how this differs from dngettext() -proper. - - - The translated string - - - - - the translation domain to use, or %NULL to use - the domain set with textdomain() - - - - message to translate - - - - plural form of the message - - - - the quantity for which translation is needed - - - - - - Compares the two #gdouble values being pointed to and returns -%TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using non-%NULL pointers to doubles as keys in a -#GHashTable. - - - %TRUE if the two keys match. - - - - - a pointer to a #gdouble key - - - - a pointer to a #gdouble key to compare with @v1 - - - - - - Converts a pointer to a #gdouble to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, -It can be passed to g_hash_table_new() as the @hash_func parameter, -when using non-%NULL pointers to doubles as keys in a #GHashTable. - - - a hash value corresponding to the key. - - - - - a pointer to a #gdouble key - - - - - - This function is a variant of g_dgettext() which supports -a disambiguating message context. GNU gettext uses the -'\004' character to separate the message context and -message id in @msgctxtid. -If 0 is passed as @msgidoffset, this function will fall back to -trying to use the deprecated convention of using "|" as a separation -character. - -This uses g_dgettext() internally. See that functions for differences -with dgettext() proper. - -Applications should normally not use this function directly, -but use the C_() macro for translations with context. - - - The translated string - - - - - the translation domain to use, or %NULL to use - the domain set with textdomain() - - - - a combined message context and message id, separated - by a \004 character - - - - the offset of the message id in @msgctxid - - - - - - This function is a variant of g_dgettext() which supports -a disambiguating message context. GNU gettext uses the -'\004' character to separate the message context and -message id in @msgctxtid. - -This uses g_dgettext() internally. See that functions for differences -with dgettext() proper. - -This function differs from C_() in that it is not a macro and -thus you may use non-string-literals as context and msgid arguments. - - - The translated string - - - - - the translation domain to use, or %NULL to use - the domain set with textdomain() - - - - the message context - - - - the message - - - - - - Returns the value of the environment variable @variable in the -provided list @envp. - - - the value of the environment variable, or %NULL if - the environment variable is not set in @envp. The returned - string is owned by @envp, and will be freed if @variable is - set or unset again. - - - - - - an environment list (eg, as returned from g_get_environ()), or %NULL - for an empty environment list - - - - - - the environment variable to get - - - - - - Sets the environment variable @variable in the provided list -@envp to @value. - - - - the updated environment list. Free it using g_strfreev(). - - - - - - - - an environment list that can be freed using g_strfreev() (e.g., as - returned from g_get_environ()), or %NULL for an empty - environment list - - - - - - the environment variable to set, must not - contain '=' - - - - the value for to set the variable to - - - - whether to change the variable if it already exists - - - - - - Removes the environment variable @variable from the provided -environment @envp. - - - - the updated environment list. Free it using g_strfreev(). - - - - - - - - an environment list that can be freed using g_strfreev() (e.g., as - returned from g_get_environ()), or %NULL for an empty environment list - - - - - - the environment variable to remove, must not - contain '=' - - - - - - Gets a #GFileError constant based on the passed-in @err_no. -For example, if you pass in `EEXIST` this function returns -#G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably -assume that all #GFileError values will exist. - -Normally a #GFileError value goes into a #GError returned -from a function that manipulates files. So you would use -g_file_error_from_errno() when constructing a #GError. - - - #GFileError corresponding to the given @errno - - - - - an "errno" value - - - - - - - - - - - Reads an entire file into allocated memory, with good error -checking. - -If the call was successful, it returns %TRUE and sets @contents to the file -contents and @length to the length of the file contents in bytes. The string -stored in @contents will be nul-terminated, so for text files you can pass -%NULL for the @length argument. If the call was not successful, it returns -%FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error -codes are those in the #GFileError enumeration. In the error case, -@contents is set to %NULL and @length is set to zero. - - - %TRUE on success, %FALSE if an error occurred - - - - - name of a file to read contents from, in the GLib file name encoding - - - - location to store an allocated string, use g_free() to free - the returned string - - - - - - location to store length in bytes of the contents, or %NULL - - - - - - Opens a file for writing in the preferred directory for temporary -files (as returned by g_get_tmp_dir()). - -@tmpl should be a string in the GLib file name encoding containing -a sequence of six 'X' characters, as the parameter to g_mkstemp(). -However, unlike these functions, the template should only be a -basename, no directory components are allowed. If template is -%NULL, a default template is used. - -Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not -modified, and might thus be a read-only literal string. - -Upon success, and if @name_used is non-%NULL, the actual name used -is returned in @name_used. This string should be freed with g_free() -when not needed any longer. The returned name is in the GLib file -name encoding. - - - A file handle (as from open()) to the file opened for - reading and writing. The file is opened in binary mode on platforms - where there is a difference. The file handle should be closed with - close(). In case of errors, -1 is returned and @error will be set. - - - - - Template for file name, as in - g_mkstemp(), basename only, or %NULL for a default template - - - - location to store actual name used, - or %NULL - - - - - - Reads the contents of the symbolic link @filename like the POSIX -readlink() function. The returned string is in the encoding used -for filenames. Use g_filename_to_utf8() to convert it to UTF-8. - - - A newly-allocated string with the contents of - the symbolic link, or %NULL if an error occurred. - - - - - the symbolic link - - - - - - Writes all of @contents to a file named @filename, with good error checking. -If a file called @filename already exists it will be overwritten. - -This write is atomic in the sense that it is first written to a temporary -file which is then renamed to the final name. Notes: - -- On UNIX, if @filename already exists hard links to @filename will break. - Also since the file is recreated, existing permissions, access control - lists, metadata etc. may be lost. If @filename is a symbolic link, - the link itself will be replaced, not the linked file. - -- On UNIX, if @filename already exists and is non-empty, and if the system - supports it (via a journalling filesystem or equivalent), the fsync() - call (or equivalent) will be used to ensure atomic replacement: @filename - will contain either its old contents or @contents, even in the face of - system power loss, the disk being unsafely removed, etc. - -- On UNIX, if @filename does not already exist or is empty, there is a - possibility that system power loss etc. after calling this function will - leave @filename empty or full of NUL bytes, depending on the underlying - filesystem. - -- On Windows renaming a file will not remove an existing file with the - new name, so on Windows there is a race condition between the existing - file being removed and the temporary file being renamed. - -- On Windows there is no way to remove a file that is open to some - process, or mapped into memory. Thus, this function will fail if - @filename already exists and is open. - -If the call was successful, it returns %TRUE. If the call was not successful, -it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. -Possible error codes are those in the #GFileError enumeration. - -Note that the name for the temporary file is constructed by appending up -to 7 characters to @filename. - - - %TRUE on success, %FALSE if an error occurred - - - - - name of a file to write @contents to, in the GLib file name - encoding - - - - string to write to the file - - - - - - length of @contents, or -1 if @contents is a nul-terminated string - - - - - - Returns %TRUE if any of the tests in the bitfield @test are -%TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` -will return %TRUE if the file exists; the check whether it's a -directory doesn't matter since the existence test is %TRUE. With -the current set of available tests, there's no point passing in -more than one test at a time. - -Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, -so for a symbolic link to a regular file g_file_test() will return -%TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. - -Note, that for a dangling symbolic link g_file_test() will return -%TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. - -You should never use g_file_test() to test whether it is safe -to perform an operation, because there is always the possibility -of the condition changing before you actually perform the operation. -For example, you might think you could use %G_FILE_TEST_IS_SYMLINK -to know whether it is safe to write to a file without being -tricked into writing into a different location. It doesn't work! -|[<!-- language="C" --> - // DON'T DO THIS - if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) - { - fd = g_open (filename, O_WRONLY); - // write to fd - } -]| - -Another thing to note is that %G_FILE_TEST_EXISTS and -%G_FILE_TEST_IS_EXECUTABLE are implemented using the access() -system call. This usually doesn't matter, but if your program -is setuid or setgid it means that these tests will give you -the answer for the real user ID and group ID, rather than the -effective user ID and group ID. - -On Windows, there are no symlinks, so testing for -%G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for -%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and -its name indicates that it is executable, checking for well-known -extensions and those listed in the `PATHEXT` environment variable. - - - whether a test was %TRUE - - - - - a filename to test in the - GLib file name encoding - - - - bitfield of #GFileTest flags - - - - - - Returns the display basename for the particular filename, guaranteed -to be valid UTF-8. The display name might not be identical to the filename, -for instance there might be problems converting it to UTF-8, and some files -can be translated in the display. - -If GLib cannot make sense of the encoding of @filename, as a last resort it -replaces unknown characters with U+FFFD, the Unicode replacement character. -You can search the result for the UTF-8 encoding of this character (which is -"\357\277\275" in octal notation) to find out if @filename was in an invalid -encoding. - -You must pass the whole absolute pathname to this functions so that -translation of well known locations can be done. - -This function is preferred over g_filename_display_name() if you know the -whole path, as it allows translation. - - - a newly allocated string containing - a rendition of the basename of the filename in valid UTF-8 - - - - - an absolute pathname in the - GLib file name encoding - - - - - - Converts a filename into a valid UTF-8 string. The conversion is -not necessarily reversible, so you should keep the original around -and use the return value of this function only for display purposes. -Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL -even if the filename actually isn't in the GLib file name encoding. - -If GLib cannot make sense of the encoding of @filename, as a last resort it -replaces unknown characters with U+FFFD, the Unicode replacement character. -You can search the result for the UTF-8 encoding of this character (which is -"\357\277\275" in octal notation) to find out if @filename was in an invalid -encoding. - -If you know the whole pathname of the file you should use -g_filename_display_basename(), since that allows location-based -translation of filenames. - - - a newly allocated string containing - a rendition of the filename in valid UTF-8 - - - - - a pathname hopefully in the - GLib file name encoding - - - - - - Converts an escaped ASCII-encoded URI to a local filename in the -encoding used for filenames. - - - a newly-allocated string holding - the resulting filename, or %NULL on an error. - - - - - a uri describing a filename (escaped, encoded in ASCII). - - - - Location to store hostname for the URI. - If there is no hostname in the URI, %NULL will be - stored in this location. - - - - - - Converts a string from UTF-8 to the encoding GLib uses for -filenames. Note that on Windows GLib uses UTF-8 for filenames; -on other platforms, this function indirectly depends on the -[current locale][setlocale]. - -The input string shall not contain nul characters even if the @len -argument is positive. A nul character found inside the string will result -in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is -not UTF-8 and the conversion output contains a nul character, the error -%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. - - - - The converted string, or %NULL on an error. - - - - - a UTF-8 encoded string. - - - - the length of the string, or -1 if the string is - nul-terminated. - - - - location to store the number of bytes in - the input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in - the output buffer (not including the terminating nul). - - - - - - Converts an absolute filename to an escaped ASCII-encoded URI, with the path -component following Section 3.3. of RFC 2396. - - - a newly-allocated string holding the resulting - URI, or %NULL on an error. - - - - - an absolute filename specified in the GLib file - name encoding, which is the on-disk file name bytes on Unix, and UTF-8 - on Windows - - - - A UTF-8 encoded hostname, or %NULL for none. - - - - - - Converts a string which is in the encoding used by GLib for -filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 -for filenames; on other platforms, this function indirectly depends on -the [current locale][setlocale]. - -The input string shall not contain nul characters even if the @len -argument is positive. A nul character found inside the string will result -in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. -If the source encoding is not UTF-8 and the conversion output contains a -nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the -function returns %NULL. Use g_convert() to produce output that -may contain embedded nul characters. - - - The converted string, or %NULL on an error. - - - - - a string in the encoding for filenames - - - - the length of the string, or -1 if the string is - nul-terminated (Note that some encodings may allow nul - bytes to occur inside strings. In that case, using -1 - for the @len parameter is unsafe) - - - - location to store the number of bytes in the - input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in the output - buffer (not including the terminating nul). - - - - - - Locates the first executable named @program in the user's path, in the -same way that execvp() would locate it. Returns an allocated string -with the absolute path name, or %NULL if the program is not found in -the path. If @program is already an absolute path, returns a copy of -@program if @program exists and is executable, and %NULL otherwise. - -On Windows, if @program does not have a file type suffix, tries -with the suffixes .exe, .cmd, .bat and .com, and the suffixes in -the `PATHEXT` environment variable. - -On Windows, it looks for the file in the same way as CreateProcess() -would. This means first in the directory where the executing -program was loaded from, then in the current directory, then in the -Windows 32-bit system directory, then in the Windows directory, and -finally in the directories in the `PATH` environment variable. If -the program is found, the return value contains the full name -including the type suffix. - - - a newly-allocated - string with the absolute path, or %NULL - - - - - a program name in the GLib file name encoding - - - - - - Formats a size (for example the size of a file) into a human readable -string. Sizes are rounded to the nearest size prefix (kB, MB, GB) -and are displayed rounded to the nearest tenth. E.g. the file size -3292528 bytes will be converted into the string "3.2 MB". The returned string -is UTF-8, and may use a non-breaking space to separate the number and units, -to ensure they aren’t separated when line wrapped. - -The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). - -This string should be freed with g_free() when not needed any longer. - -See g_format_size_full() for more options about how the size might be -formatted. - - - a newly-allocated formatted string containing - a human readable file size - - - - - a size in bytes - - - - - - Formats a size (for example the size of a file) into a human -readable string. Sizes are rounded to the nearest size prefix -(KB, MB, GB) and are displayed rounded to the nearest tenth. -E.g. the file size 3292528 bytes will be converted into the -string "3.1 MB". - -The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). - -This string should be freed with g_free() when not needed any longer. - This function is broken due to its use of SI - suffixes to denote IEC units. Use g_format_size() instead. - - - a newly-allocated formatted string - containing a human readable file size - - - - - a size in bytes - - - - - - Formats a size. - -This function is similar to g_format_size() but allows for flags -that modify the output. See #GFormatSizeFlags. - - - a newly-allocated formatted string - containing a human readable file size - - - - - a size in bytes - - - - #GFormatSizeFlags to modify the output - - - - - - An implementation of the standard fprintf() function which supports -positional parameters, as specified in the Single Unix Specification. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - the stream to write to. - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the arguments to insert in the output. - - - - - - Frees the memory pointed to by @mem. - -If @mem is %NULL it simply returns, so there is no need to check @mem -against %NULL before calling this function. - - - - - - - the memory to free - - - - - - Gets a human-readable name for the application, as set by -g_set_application_name(). This name should be localized if -possible, and is intended for display to the user. Contrast with -g_get_prgname(), which gets a non-localized name. If -g_set_application_name() has not been called, returns the result of -g_get_prgname() (which may be %NULL if g_set_prgname() has also not -been called). - - - human-readable application - name. May return %NULL - - - - - Obtains the character set for the [current locale][setlocale]; you -might use this character set as an argument to g_convert(), to convert -from the current locale's encoding to some other encoding. (Frequently -g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) - -On Windows the character set returned by this function is the -so-called system default ANSI code-page. That is the character set -used by the "narrow" versions of C library and Win32 functions that -handle file names. It might be different from the character set -used by the C library's current locale. - -On Linux, the character set is found by consulting nl_langinfo() if -available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG` -and `CHARSET` are queried in order. - -The return value is %TRUE if the locale's encoding is UTF-8, in that -case you can perhaps avoid calling g_convert(). - -The string returned in @charset is not allocated, and should not be -freed. - - - %TRUE if the returned charset is UTF-8 - - - - - return location for character set - name, or %NULL. - - - - - - Gets the character set for the current locale. - - - a newly allocated string containing the name - of the character set. This string must be freed with g_free(). - - - - - Obtains the character set used by the console attached to the process, -which is suitable for printing output to the terminal. - -Usually this matches the result returned by g_get_charset(), but in -environments where the locale's character set does not match the encoding -of the console this function tries to guess a more suitable value instead. - -On Windows the character set returned by this function is the -output code page used by the console associated with the calling process. -If the codepage can't be determined (for example because there is no -console attached) UTF-8 is assumed. - -The return value is %TRUE if the locale's encoding is UTF-8, in that -case you can perhaps avoid calling g_convert(). - -The string returned in @charset is not allocated, and should not be -freed. - - - %TRUE if the returned charset is UTF-8 - - - - - return location for character set - name, or %NULL. - - - - - - Gets the current directory. - -The returned string should be freed when no longer needed. -The encoding of the returned string is system defined. -On Windows, it is always UTF-8. - -Since GLib 2.40, this function will return the value of the "PWD" -environment variable if it is set and it happens to be the same as -the current directory. This can make a difference in the case that -the current directory is the target of a symbolic link. - - - the current directory - - - - - Equivalent to the UNIX gettimeofday() function, but portable. - -You may find g_get_real_time() to be more convenient. - #GTimeVal is not year-2038-safe. Use g_get_real_time() - instead. - - - - - - - #GTimeVal structure in which to store current time. - - - - - - Gets the list of environment variables for the current process. - -The list is %NULL terminated and each item in the list is of the -form 'NAME=VALUE'. - -This is equivalent to direct access to the 'environ' global variable, -except portable. - -The return value is freshly allocated and it should be freed with -g_strfreev() when it is no longer needed. - - - - the list of environment variables - - - - - - - Determines the preferred character sets used for filenames. -The first character set from the @charsets is the filename encoding, the -subsequent character sets are used when trying to generate a displayable -representation of a filename, see g_filename_display_name(). - -On Unix, the character sets are determined by consulting the -environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. -On Windows, the character set used in the GLib API is always UTF-8 -and said environment variables have no effect. - -`G_FILENAME_ENCODING` may be set to a comma-separated list of -character set names. The special token "\@locale" is taken -to mean the character set for the [current locale][setlocale]. -If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, -the character set of the current locale is taken as the filename -encoding. If neither environment variable is set, UTF-8 is taken -as the filename encoding, but the character set of the current locale -is also put in the list of encodings. - -The returned @charsets belong to GLib and must not be freed. - -Note that on Unix, regardless of the locale character set or -`G_FILENAME_ENCODING` value, the actual file names present -on a system might be in any random encoding or just gibberish. - - - %TRUE if the filename encoding is UTF-8. - - - - - - return location for the %NULL-terminated list of encoding names - - - - - - - - Gets the current user's home directory. - -As with most UNIX tools, this function will return the value of the -`HOME` environment variable if it is set to an existing absolute path -name, falling back to the `passwd` file in the case that it is unset. - -If the path given in `HOME` is non-absolute, does not exist, or is -not a directory, the result is undefined. - -Before version 2.36 this function would ignore the `HOME` environment -variable, taking the value from the `passwd` database instead. This was -changed to increase the compatibility of GLib with other programs (and -the XDG basedir specification) and to increase testability of programs -based on GLib (by making it easier to run them from test frameworks). - -If your program has a strong requirement for either the new or the -old behaviour (and if you don't wish to increase your GLib -dependency to ensure that the new behaviour is in effect) then you -should either directly check the `HOME` environment variable yourself -or unset it before calling any functions in GLib. - - - the current user's home directory - - - - - Return a name for the machine. - -The returned name is not necessarily a fully-qualified domain name, -or even present in DNS or some other name service at all. It need -not even be unique on your local network or site, but usually it -is. Callers should not rely on the return value having any specific -properties like uniqueness for security purposes. Even if the name -of the machine is changed while an application is running, the -return value from this function does not change. The returned -string is owned by GLib and should not be modified or freed. If no -name can be determined, a default fixed string "localhost" is -returned. - -The encoding of the returned string is UTF-8. - - - the host name of the machine. - - - - - Computes a list of applicable locale names, which can be used to -e.g. construct locale-dependent filenames or search paths. The returned -list is sorted from most desirable to least desirable and always contains -the default locale "C". - -For example, if LANGUAGE=de:en_US, then the returned list is -"de", "en_US", "en", "C". - -This function consults the environment variables `LANGUAGE`, `LC_ALL`, -`LC_MESSAGES` and `LANG` to find the list of locales specified by the -user. - - - a %NULL-terminated array of strings owned by GLib - that must not be modified or freed. - - - - - - - Computes a list of applicable locale names with a locale category name, -which can be used to construct the fallback locale-dependent filenames -or search paths. The returned list is sorted from most desirable to -least desirable and always contains the default locale "C". - -This function consults the environment variables `LANGUAGE`, `LC_ALL`, -@category_name, and `LANG` to find the list of locales specified by the -user. - -g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES"). - - - a %NULL-terminated array of strings owned by - the thread g_get_language_names_with_category was called from. - It must not be modified or freed. It must be copied if planned to be used in another thread. - - - - - - - a locale category name - - - - - - Returns a list of derived variants of @locale, which can be used to -e.g. construct locale-dependent filenames or search paths. The returned -list is sorted from most desirable to least desirable. -This function handles territory, charset and extra locale modifiers. See -[`setlocale(3)`](man:setlocale) for information about locales and their format. - -@locale itself is guaranteed to be returned in the output. - -For example, if @locale is `fr_BE`, then the returned list -is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list -is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`, -`en.UTF-8`, `en@euro`, `en`. - -If you need the list of variants for the current locale, -use g_get_language_names(). - - - a newly - allocated array of newly allocated strings with the locale variants. Free with - g_strfreev(). - - - - - - - a locale identifier - - - - - - Queries the system monotonic time. - -The monotonic clock will always increase and doesn't suffer -discontinuities when the user (or NTP) changes the system time. It -may or may not continue to tick during times where the machine is -suspended. - -We try to use the clock that corresponds as closely as possible to -the passage of time as measured by system calls such as poll() but it -may not always be possible to do this. - - - the monotonic time, in microseconds - - - - - Determine the approximate number of threads that the system will -schedule simultaneously for this process. This is intended to be -used as a parameter to g_thread_pool_new() for CPU bound tasks and -similar cases. - - - Number of schedulable threads, always greater than 0 - - - - - Get information about the operating system. - -On Linux this comes from the `/etc/os-release` file. On other systems, it may -come from a variety of sources. You can either use the standard key names -like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example, -`/etc/os-release` provides a number of other less commonly used values that may -be useful. No key is guaranteed to be provided, so the caller should always -check if the result is %NULL. - - - The associated value for the requested key or %NULL if - this information is not provided. - - - - - a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. - - - - - - Gets the name of the program. This name should not be localized, -in contrast to g_get_application_name(). - -If you are using #GApplication the program name is set in -g_application_run(). In case of GDK or GTK+ it is set in -gdk_init(), which is called by gtk_init() and the -#GtkApplication::startup handler. The program name is found by -taking the last component of @argv[0]. - - - the name of the program, - or %NULL if it has not been set yet. The returned string belongs - to GLib and must not be modified or freed. - - - - - Gets the real name of the user. This usually comes from the user's -entry in the `passwd` file. The encoding of the returned string is -system-defined. (On Windows, it is, however, always UTF-8.) If the -real user name cannot be determined, the string "Unknown" is -returned. - - - the user's real name. - - - - - Queries the system wall-clock time. - -This call is functionally equivalent to g_get_current_time() except -that the return value is often more convenient than dealing with a -#GTimeVal. - -You should only use this call if you are actually interested in the real -wall-clock time. g_get_monotonic_time() is probably more useful for -measuring intervals. - - - the number of microseconds since January 1, 1970 UTC. - - - - - Returns an ordered list of base directories in which to access -system-wide configuration information. - -On UNIX platforms this is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). -In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. - -On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined. -If `XDG_CONFIG_DIRS` is undefined, the directory that contains application -data for all users is used instead. A typical path is -`C:\Documents and Settings\All Users\Application Data`. -This folder is used for application data -that is not user specific. For example, an application can store -a spell-check dictionary, a database of clip art, or a log file in the -CSIDL_COMMON_APPDATA folder. This information will not roam and is available -to anyone using the computer. - - - - a %NULL-terminated array of strings owned by GLib that must not be - modified or freed. - - - - - - - Returns an ordered list of base directories in which to access -system-wide application data. - -On UNIX platforms this is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) -In this case the list of directories retrieved will be `XDG_DATA_DIRS`. - -On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined. -If `XDG_DATA_DIRS` is undefined, -the first elements in the list are the Application Data -and Documents folders for All Users. (These can be determined only -on Windows 2000 or later and are not present in the list on other -Windows versions.) See documentation for CSIDL_COMMON_APPDATA and -CSIDL_COMMON_DOCUMENTS. - -Then follows the "share" subfolder in the installation folder for -the package containing the DLL that calls this function, if it can -be determined. - -Finally the list contains the "share" subfolder in the installation -folder for GLib, and in the installation folder for the package the -application's .exe file belongs to. - -The installation folders above are determined by looking up the -folder where the module (DLL or EXE) in question is located. If the -folder's name is "bin", its parent is used, otherwise the folder -itself. - -Note that on Windows the returned list can vary depending on where -this function is called. - - - - a %NULL-terminated array of strings owned by GLib that must not be - modified or freed. - - - - - - - Gets the directory to use for temporary files. - -On UNIX, this is taken from the `TMPDIR` environment variable. -If the variable is not set, `P_tmpdir` is -used, as defined by the system C library. Failing that, a -hard-coded default of "/tmp" is returned. - -On Windows, the `TEMP` environment variable is used, with the -root directory of the Windows installation (eg: "C:\") used -as a default. - -The encoding of the returned string is system-defined. On Windows, -it is always UTF-8. The return value is never %NULL or the empty -string. - - - the directory to use for temporary files. - - - - - Returns a base directory in which to store non-essential, cached -data specific to particular user. - -On UNIX platforms this is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). -In this case the directory retrieved will be `XDG_CACHE_HOME`. - -On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined. -If `XDG_CACHE_HOME` is undefined, the directory that serves as a common -repository for temporary Internet files is used instead. A typical path is -`C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. -See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). - - - a string owned by GLib that - must not be modified or freed. - - - - - Returns a base directory in which to store user-specific application -configuration information such as user preferences and settings. - -On UNIX platforms this is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). -In this case the directory retrieved will be `XDG_CONFIG_HOME`. - -On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined. -If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed -to roaming) application data is used instead. See the -[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). -Note that in this case on Windows it will be the same -as what g_get_user_data_dir() returns. - - - a string owned by GLib that - must not be modified or freed. - - - - - Returns a base directory in which to access application data such -as icons that is customized for a particular user. - -On UNIX platforms this is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). -In this case the directory retrieved will be `XDG_DATA_HOME`. - -On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME` -is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as -opposed to roaming) application data is used instead. See the -[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). -Note that in this case on Windows it will be the same -as what g_get_user_config_dir() returns. - - - a string owned by GLib that must - not be modified or freed. - - - - - Gets the user name of the current user. The encoding of the returned -string is system-defined. On UNIX, it might be the preferred file name -encoding, or something else, and there is no guarantee that it is even -consistent on a machine. On Windows, it is always UTF-8. - - - the user name of the current user. - - - - - Returns a directory that is unique to the current user on the local -system. - -This is determined using the mechanisms described -in the -[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). -This is the directory -specified in the `XDG_RUNTIME_DIR` environment variable. -In the case that this variable is not set, we return the value of -g_get_user_cache_dir(), after verifying that it exists. - - - a string owned by GLib that must not be - modified or freed. - - - - - Returns the full path of a special directory using its logical id. - -On UNIX this is done using the XDG special user directories. -For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP -falls back to `$HOME/Desktop` when XDG special user directories have -not been set up. - -Depending on the platform, the user might be able to change the path -of the special directory without requiring the session to restart; GLib -will not reflect any change once the special directories are loaded. - - - the path to the specified special directory, or - %NULL if the logical id was not found. The returned string is owned by - GLib and should not be modified or freed. - - - - - the logical id of special directory - - - - - - Returns the value of an environment variable. - -On UNIX, the name and value are byte strings which might or might not -be in some consistent character set and encoding. On Windows, they are -in UTF-8. -On Windows, in case the environment variable's value contains -references to other environment variables, they are expanded. - - - the value of the environment variable, or %NULL if - the environment variable is not found. The returned string - may be overwritten by the next call to g_getenv(), g_setenv() - or g_unsetenv(). - - - - - the environment variable to get - - - - - - This is a convenience function for using a #GHashTable as a set. It -is equivalent to calling g_hash_table_replace() with @key as both the -key and the value. - -In particular, this means that if @key already exists in the hash table, then -the old copy of @key in the hash table is freed and @key replaces it in the -table. - -When a hash table only ever contains keys that have themselves as the -corresponding value it is able to be stored more efficiently. See -the discussion in the section description. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - - - Checks if @key is in @hash_table. - - - %TRUE if @key is in @hash_table, %FALSE otherwise. - - - - - a #GHashTable - - - - - - - a key to check - - - - - - Destroys all keys and values in the #GHashTable and decrements its -reference count by 1. If keys and/or values are dynamically allocated, -you should either free them first or create the #GHashTable with destroy -notifiers using g_hash_table_new_full(). In the latter case the destroy -functions you supplied will be called on all keys and values during the -destruction phase. - - - - - - - a #GHashTable - - - - - - - - - This function is deprecated and will be removed in the next major -release of GLib. It does nothing. - - - - a #GHashTable - - - - - Inserts a new key and value into a #GHashTable. - -If the key already exists in the #GHashTable its current -value is replaced with the new value. If you supplied a -@value_destroy_func when creating the #GHashTable, the old -value is freed using that function. If you supplied a -@key_destroy_func when creating the #GHashTable, the passed -key is freed using that function. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - the value to associate with the key - - - - - - Looks up a key in a #GHashTable. Note that this function cannot -distinguish between a key that is not present and one which is present -and has the value %NULL. If you need this distinction, use -g_hash_table_lookup_extended(). - - - the associated value, or %NULL if the key is not found - - - - - a #GHashTable - - - - - - - the key to look up - - - - - - Looks up a key in the #GHashTable, returning the original key and the -associated value and a #gboolean which is %TRUE if the key was found. This -is useful if you need to free the memory allocated for the original key, -for example before calling g_hash_table_remove(). - -You can actually pass %NULL for @lookup_key to test -whether the %NULL key exists, provided the hash and equal functions -of @hash_table are %NULL-safe. - - - %TRUE if the key was found in the #GHashTable - - - - - a #GHashTable - - - - - - - the key to look up - - - - return location for the original key - - - - return location for the value associated -with the key - - - - - - Removes a key and its associated value from a #GHashTable. - -If the #GHashTable was created using g_hash_table_new_full(), the -key and value are freed using the supplied destroy functions, otherwise -you have to make sure that any dynamically allocated values are freed -yourself. - - - %TRUE if the key was found and removed from the #GHashTable - - - - - a #GHashTable - - - - - - - the key to remove - - - - - - Removes all keys and their associated values from a #GHashTable. - -If the #GHashTable was created using g_hash_table_new_full(), -the keys and values are freed using the supplied destroy functions, -otherwise you have to make sure that any dynamically allocated -values are freed yourself. - - - - - - - a #GHashTable - - - - - - - - - Inserts a new key and value into a #GHashTable similar to -g_hash_table_insert(). The difference is that if the key -already exists in the #GHashTable, it gets replaced by the -new key. If you supplied a @value_destroy_func when creating -the #GHashTable, the old value is freed using that function. -If you supplied a @key_destroy_func when creating the -#GHashTable, the old key is freed using that function. - -Starting from GLib 2.40, this function returns a boolean value to -indicate whether the newly added value was already in the hash table -or not. - - - %TRUE if the key did not exist yet - - - - - a #GHashTable - - - - - - - a key to insert - - - - the value to associate with the key - - - - - - Returns the number of elements contained in the #GHashTable. - - - the number of key/value pairs in the #GHashTable. - - - - - a #GHashTable - - - - - - - - - Removes a key and its associated value from a #GHashTable without -calling the key and value destroy functions. - - - %TRUE if the key was found and removed from the #GHashTable - - - - - a #GHashTable - - - - - - - the key to remove - - - - - - Removes all keys and their associated values from a #GHashTable -without calling the key and value destroy functions. - - - - - - - a #GHashTable - - - - - - - - - Looks up a key in the #GHashTable, stealing the original key and the -associated value and returning %TRUE if the key was found. If the key was -not found, %FALSE is returned. - -If found, the stolen key and value are removed from the hash table without -calling the key and value destroy functions, and ownership is transferred to -the caller of this method; as with g_hash_table_steal(). - -You can pass %NULL for @lookup_key, provided the hash and equal functions -of @hash_table are %NULL-safe. - - - %TRUE if the key was found in the #GHashTable - - - - - a #GHashTable - - - - - - - the key to look up - - - - return location for the - original key - - - - return location - for the value associated with the key - - - - - - This function is deprecated and will be removed in the next major -release of GLib. It does nothing. - - - - a #GHashTable - - - - - Atomically decrements the reference count of @hash_table by one. -If the reference count drops to 0, all keys and values will be -destroyed, and all memory allocated by the hash table is released. -This function is MT-safe and may be called from any thread. - - - - - - - a valid #GHashTable - - - - - - - - - Appends a #GHook onto the end of a #GHookList. - - - - a #GHookList - - - the #GHook to add to the end of @hook_list - - - - - Destroys a #GHook, given its ID. - - - %TRUE if the #GHook was found in the #GHookList and destroyed - - - - - a #GHookList - - - - a hook ID - - - - - - Removes one #GHook from a #GHookList, marking it -inactive and calling g_hook_unref() on it. - - - - - - - a #GHookList - - - - the #GHook to remove - - - - - - Calls the #GHookList @finalize_hook function if it exists, -and frees the memory allocated for the #GHook. - - - - - - - a #GHookList - - - - the #GHook to free - - - - - - Inserts a #GHook into a #GHookList, before a given #GHook. - - - - - - - a #GHookList - - - - the #GHook to insert the new #GHook before - - - - the #GHook to insert - - - - - - Prepends a #GHook on the start of a #GHookList. - - - - - - - a #GHookList - - - - the #GHook to add to the start of @hook_list - - - - - - Decrements the reference count of a #GHook. -If the reference count falls to 0, the #GHook is removed -from the #GHookList and g_hook_free() is called to free it. - - - - - - - a #GHookList - - - - the #GHook to unref - - - - - - Tests if @hostname contains segments with an ASCII-compatible -encoding of an Internationalized Domain Name. If this returns -%TRUE, you should decode the hostname with g_hostname_to_unicode() -before displaying it to the user. - -Note that a hostname might contain a mix of encoded and unencoded -segments, and so it is possible for g_hostname_is_non_ascii() and -g_hostname_is_ascii_encoded() to both return %TRUE for a name. - - - %TRUE if @hostname contains any ASCII-encoded -segments. - - - - - a hostname - - - - - - Tests if @hostname is the string form of an IPv4 or IPv6 address. -(Eg, "192.168.0.1".) - - - %TRUE if @hostname is an IP address - - - - - a hostname (or IP address in string form) - - - - - - Tests if @hostname contains Unicode characters. If this returns -%TRUE, you need to encode the hostname with g_hostname_to_ascii() -before using it in non-IDN-aware contexts. - -Note that a hostname might contain a mix of encoded and unencoded -segments, and so it is possible for g_hostname_is_non_ascii() and -g_hostname_is_ascii_encoded() to both return %TRUE for a name. - - - %TRUE if @hostname contains any non-ASCII characters - - - - - a hostname - - - - - - Converts @hostname to its canonical ASCII form; an ASCII-only -string containing no uppercase letters and not ending with a -trailing dot. - - - an ASCII hostname, which must be freed, or %NULL if -@hostname is in some way invalid. - - - - - a valid UTF-8 or ASCII hostname - - - - - - Converts @hostname to its canonical presentation form; a UTF-8 -string in Unicode normalization form C, containing no uppercase -letters, no forbidden characters, and no ASCII-encoded segments, -and not ending with a trailing dot. - -Of course if @hostname is not an internationalized hostname, then -the canonical presentation form will be entirely ASCII. - - - a UTF-8 hostname, which must be freed, or %NULL if -@hostname is in some way invalid. - - - - - a valid UTF-8 or ASCII hostname - - - - - - Converts a 32-bit integer value from host to network byte order. - - - - a 32-bit integer value in host byte order - - - - - Converts a 16-bit integer value from host to network byte order. - - - - a 16-bit integer value in host byte order - - - - - Same as the standard UNIX routine iconv(), but -may be implemented via libiconv on UNIX flavors that lack -a native implementation. - -GLib provides g_convert() and g_locale_to_utf8() which are likely -more convenient than the raw iconv wrappers. - -Note that the behaviour of iconv() for characters which are valid in the -input character set, but which have no representation in the output character -set, is implementation defined. This function may return success (with a -positive number of non-reversible conversions as replacement characters were -used), or it may return -1 and set an error such as %EILSEQ, in such a -situation. - - - count of non-reversible conversions, or -1 on error - - - - - conversion descriptor from g_iconv_open() - - - - bytes to convert - - - - inout parameter, bytes remaining to convert in @inbuf - - - - converted output bytes - - - - inout parameter, bytes available to fill in @outbuf - - - - - - Same as the standard UNIX routine iconv_open(), but -may be implemented via libiconv on UNIX flavors that lack -a native implementation. - -GLib provides g_convert() and g_locale_to_utf8() which are likely -more convenient than the raw iconv wrappers. - - - a "conversion descriptor", or (GIConv)-1 if - opening the converter failed. - - - - - destination codeset - - - - source codeset - - - - - - Adds a function to be called whenever there are no higher priority -events pending to the default main loop. The function is given the -default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function -returns %FALSE it is automatically removed from the list of event -sources and will not be called again. - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - - - the ID (greater than 0) of the event source. - - - - - function to call - - - - data to pass to @function. - - - - - - Adds a function to be called whenever there are no higher priority -events pending. If the function returns %FALSE it is automatically -removed from the list of event sources and will not be called again. - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - - - the ID (greater than 0) of the event source. - - - - - the priority of the idle source. Typically this will be in the - range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - - - - function to call - - - - data to pass to @function - - - - function to call when the idle is removed, or %NULL - - - - - - Removes the idle function with the given data. - - - %TRUE if an idle source was found and removed. - - - - - the data for the idle source's callback. - - - - - - Creates a new idle source. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. Note that the default priority for idle sources is -%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which -have a default priority of %G_PRIORITY_DEFAULT. - - - the newly-created idle source - - - - - Compares the two #gint64 values being pointed to and returns -%TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using non-%NULL pointers to 64-bit integers as keys in a -#GHashTable. - - - %TRUE if the two keys match. - - - - - a pointer to a #gint64 key - - - - a pointer to a #gint64 key to compare with @v1 - - - - - - Converts a pointer to a #gint64 to a hash value. - -It can be passed to g_hash_table_new() as the @hash_func parameter, -when using non-%NULL pointers to 64-bit integer values as keys in a -#GHashTable. - - - a hash value corresponding to the key. - - - - - a pointer to a #gint64 key - - - - - - Compares the two #gint values being pointed to and returns -%TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_equal_func -parameter, when using non-%NULL pointers to integers as keys in a -#GHashTable. - -Note that this function acts on pointers to #gint, not on #gint -directly: if your hash table's keys are of the form -`GINT_TO_POINTER (n)`, use g_direct_equal() instead. - - - %TRUE if the two keys match. - - - - - a pointer to a #gint key - - - - a pointer to a #gint key to compare with @v1 - - - - - - Converts a pointer to a #gint to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, -when using non-%NULL pointers to integer values as keys in a #GHashTable. - -Note that this function acts on pointers to #gint, not on #gint -directly: if your hash table's keys are of the form -`GINT_TO_POINTER (n)`, use g_direct_hash() instead. - - - a hash value corresponding to the key. - - - - - a pointer to a #gint key - - - - - - Returns a canonical representation for @string. Interned strings -can be compared for equality by comparing the pointers, instead of -using strcmp(). g_intern_static_string() does not copy the string, -therefore @string must not be freed or modified. - -This function must not be used before library constructors have finished -running. In particular, this means it cannot be used to initialize global -variables in C++. - - - a canonical representation for the string - - - - - a static string - - - - - - Returns a canonical representation for @string. Interned strings -can be compared for equality by comparing the pointers, instead of -using strcmp(). - -This function must not be used before library constructors have finished -running. In particular, this means it cannot be used to initialize global -variables in C++. - - - a canonical representation for the string - - - - - a string - - - - - - Adds the #GIOChannel into the default main loop context -with the default priority. - - - the event source id - - - - - a #GIOChannel - - - - the condition to watch for - - - - the function to call when the condition is satisfied - - - - user data to pass to @func - - - - - - Adds the #GIOChannel into the default main loop context -with the given priority. - -This internally creates a main loop source using g_io_create_watch() -and attaches it to the main loop context with g_source_attach(). -You can do these steps manually if you need greater control. - - - the event source id - - - - - a #GIOChannel - - - - the priority of the #GIOChannel source - - - - the condition to watch for - - - - the function to call when the condition is satisfied - - - - user data to pass to @func - - - - the function to call when the source is removed - - - - - - Converts an `errno` error number to a #GIOChannelError. - - - a #GIOChannelError error number, e.g. - %G_IO_CHANNEL_ERROR_INVAL. - - - - - an `errno` error number, e.g. `EINVAL` - - - - - - - - - - - Creates a #GSource that's dispatched when @condition is met for the -given @channel. For example, if condition is #G_IO_IN, the source will -be dispatched when there's data available for reading. - -The callback function invoked by the #GSource should be added with -g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc). - -g_io_add_watch() is a simpler interface to this same functionality, for -the case where you want to add the source to the default main loop context -at the default priority. - -On Windows, polling a #GSource created to watch a channel for a socket -puts the socket in non-blocking mode. This is a side-effect of the -implementation and unavoidable. - - - a new #GSource - - - - - a #GIOChannel to watch - - - - conditions to watch for - - - - - - - - - - - A convenience macro to get the next element in a #GList. -Note that it is considered perfectly acceptable to access -@list->next directly. - - - - an element in a #GList - - - - - A convenience macro to get the previous element in a #GList. -Note that it is considered perfectly acceptable to access -@list->prev directly. - - - - an element in a #GList - - - - - Gets the names of all variables set in the environment. - -Programs that want to be portable to Windows should typically use -this function and g_getenv() instead of using the environ array -from the C library directly. On Windows, the strings in the environ -array are in system codepage encoding, while in most of the typical -use cases for environment variables in GLib-using programs you want -the UTF-8 encoding that this function and g_getenv() provide. - - - - a %NULL-terminated list of strings which must be freed with - g_strfreev(). - - - - - - - Converts a string from UTF-8 to the encoding used for strings by -the C runtime (usually the same as that used by the operating -system) in the [current locale][setlocale]. On Windows this means -the system codepage. - -The input string shall not contain nul characters even if the @len -argument is positive. A nul character found inside the string will result -in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert -input that may contain embedded nul characters. - - - - A newly-allocated buffer containing the converted string, - or %NULL on an error, and error will be set. - - - - - - - a UTF-8 encoded string - - - - the length of the string, or -1 if the string is - nul-terminated. - - - - location to store the number of bytes in the - input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in the output - buffer (not including the terminating nul). - - - - - - Converts a string which is in the encoding used for strings by -the C runtime (usually the same as that used by the operating -system) in the [current locale][setlocale] into a UTF-8 string. - -If the source encoding is not UTF-8 and the conversion output contains a -nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the -function returns %NULL. -If the source encoding is UTF-8, an embedded nul character is treated with -the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with -earlier versions of this library. Use g_convert() to produce output that -may contain embedded nul characters. - - - The converted string, or %NULL on an error. - - - - - a string in the - encoding of the current locale. On Windows - this means the system codepage. - - - - - - the length of the string, or -1 if the string is - nul-terminated (Note that some encodings may allow nul - bytes to occur inside strings. In that case, using -1 - for the @len parameter is unsafe) - - - - location to store the number of bytes in the - input string that were successfully converted, or %NULL. - Even if the conversion was successful, this may be - less than @len if there were partial characters - at the end of the input. If the error - %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - stored will be the byte offset after the last valid - input sequence. - - - - the number of bytes stored in the output - buffer (not including the terminating nul). - - - - - - Logs an error or debugging message. - -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for -details of the debugging options this provides. - -If g_log_default_handler() is used as the log handler function, a new-line -character will automatically be appended to @..., and need not be entered -manually. - -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). - - - - - - - the log domain, usually #G_LOG_DOMAIN, or %NULL -for the default - - - - the log level, either from #GLogLevelFlags - or a user-defined level - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - The default log handler set up by GLib; g_log_set_default_handler() -allows to install an alternate default log handler. -This is used if no log handler has been set for the particular log -domain and log level combination. It outputs the message to stderr -or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically -prints a new-line character after the message, so one does not need to be -manually included in @message. - -The behavior of this log handler can be influenced by a number of -environment variables: - -- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which - messages should be prefixed by the program name and PID of the - aplication. - -- `G_MESSAGES_DEBUG`: A space-separated list of log domains for - which debug and informational messages are printed. By default - these messages are not printed. - -stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, -%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for -the rest. - -This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - - - - - the log domain of the message, or %NULL for the -default "" application domain - - - - the level of the message - - - - the message - - - - data passed from g_log() which is unused - - - - - - Removes the log handler. - -This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - - - - - the log domain - - - - the id of the handler, which was returned - in g_log_set_handler() - - - - - - Sets the message levels which are always fatal, in any log domain. -When a message with any of these levels is logged the program terminates. -You can only set the levels defined by GLib to be fatal. -%G_LOG_LEVEL_ERROR is always fatal. - -You can also make some message levels fatal at runtime by setting -the `G_DEBUG` environment variable (see -[Running GLib Applications](glib-running.html)). - -Libraries should not call this function, as it affects all messages logged -by a process, including those from other libraries. - -Structured log messages (using g_log_structured() and -g_log_structured_array()) are fatal only if the default log writer is used; -otherwise it is up to the writer function to determine which log messages -are fatal. See [Using Structured Logging][using-structured-logging]. - - - the old fatal mask - - - - - the mask containing bits set for each level - of error which is to be fatal - - - - - - Installs a default log handler which is used if no -log handler has been set for the particular log domain -and log level combination. By default, GLib uses -g_log_default_handler() as default log handler. - -This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - the previous default log handler - - - - - the log handler function - - - - data passed to the log handler - - - - - - Sets the log levels which are fatal in the given domain. -%G_LOG_LEVEL_ERROR is always fatal. - -This has no effect on structured log messages (using g_log_structured() or -g_log_structured_array()). To change the fatal behaviour for specific log -messages, programs must install a custom log writer function using -g_log_set_writer_func(). See -[Using Structured Logging][using-structured-logging]. - -This function is mostly intended to be used with -%G_LOG_LEVEL_CRITICAL. You should typically not set -%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or -%G_LOG_LEVEL_DEBUG as fatal except inside of test programs. - - - the old fatal mask for the log domain - - - - - the log domain - - - - the new fatal mask - - - - - - Sets the log handler for a domain and a set of log levels. -To handle fatal and recursive messages the @log_levels parameter -must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION -bit flags. - -Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if -you want to set a handler for this log level you must combine it with -#G_LOG_FLAG_FATAL. - -This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - -Here is an example for adding a log handler for all warning messages -in the default domain: -|[<!-- language="C" --> -g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL - | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| - -This example adds a log handler for all critical messages from GTK+: -|[<!-- language="C" --> -g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL - | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| - -This example adds a log handler for all messages from GLib: -|[<!-- language="C" --> -g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL - | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| - - - the id of the new handler - - - - - the log domain, or %NULL for the default "" - application domain - - - - the log levels to apply the log handler for. - To handle fatal and recursive messages as well, combine - the log levels with the #G_LOG_FLAG_FATAL and - #G_LOG_FLAG_RECURSION bit flags. - - - - the log handler function - - - - data passed to the log handler - - - - - - Like g_log_set_handler(), but takes a destroy notify for the @user_data. - -This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. - - - the id of the new handler - - - - - the log domain, or %NULL for the default "" - application domain - - - - the log levels to apply the log handler for. - To handle fatal and recursive messages as well, combine - the log levels with the #G_LOG_FLAG_FATAL and - #G_LOG_FLAG_RECURSION bit flags. - - - - the log handler function - - - - data passed to the log handler - - - - destroy notify for @user_data, or %NULL - - - - - - Set a writer function which will be called to format and write out each log -message. Each program should set a writer function, or the default writer -(g_log_writer_default()) will be used. - -Libraries **must not** call this function — only programs are allowed to -install a writer function, as there must be a single, central point where -log messages are formatted and outputted. - -There can only be one writer function. It is an error to set more than one. - - - - - - - log writer function, which must not be %NULL - - - - user data to pass to @func - - - - function to free @user_data once it’s - finished with, if non-%NULL - - - - - - Log a message with structured data. The message will be passed through to -the log writer set by the application using g_log_set_writer_func(). If the -message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will -be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns -%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. -See the documentation for #GLogWriterFunc for information on chaining -writers. - -The structured data is provided as key–value pairs, where keys are UTF-8 -strings, and values are arbitrary pointers — typically pointing to UTF-8 -strings, but that is not a requirement. To pass binary (non-nul-terminated) -structured data, use g_log_structured_array(). The keys for structured data -should follow the [systemd journal -fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) -specification. It is suggested that custom keys are namespaced according to -the code which sets them. For example, custom keys from GLib all have a -`GLIB_` prefix. - -The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will -be converted into a -[`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=) -field. The format string will have its placeholders substituted for the provided -values and be converted into a -[`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=) -field. - -Other fields you may commonly want to pass into this function: - - * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=) - * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=) - * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=) - * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=) - * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) - -Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by -the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), -g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including -glib.h. - -For example: -|[<!-- language="C" --> -g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, - "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", - "MY_APPLICATION_CUSTOM_FIELD", "some debug string", - "MESSAGE", "This is a debug message about pointer %p and integer %u.", - some_pointer, some_integer); -]| - -Note that each `MESSAGE_ID` must be [uniquely and randomly -generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). -If adding a `MESSAGE_ID`, consider shipping a [message -catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with -your software. - -To pass a user data pointer to the log writer function which is specific to -this logging call, you must use g_log_structured_array() and pass the pointer -as a field with #GLogField.length set to zero, otherwise it will be -interpreted as a string. - -For example: -|[<!-- language="C" --> -const GLogField fields[] = { - { "MESSAGE", "This is a debug message.", -1 }, - { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, - { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, - { "MY_APPLICATION_STATE", state_object, 0 }, -}; -g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); -]| - -Note also that, even if no other structured fields are specified, there -must always be a `MESSAGE` key before the format string. The `MESSAGE`-format -pair has to be the last of the key-value pairs, and `MESSAGE` is the only -field for which printf()-style formatting is supported. - -The default writer function for `stdout` and `stderr` will automatically -append a new-line character after the message, so you should not add one -manually to the format string. - - - - - - - log domain, usually %G_LOG_DOMAIN - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key-value pairs of structured data to add to the log entry, followed - by the key "MESSAGE", followed by a printf()-style message format, - followed by parameters to insert in the format string - - - - - - Log a message with structured data. The message will be passed through to the -log writer set by the application using g_log_set_writer_func(). If the -message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will -be aborted at the end of this function. - -See g_log_structured() for more documentation. - -This assumes that @log_level is already present in @fields (typically as the -`PRIORITY` field). - - - - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key–value pairs of structured data to add - to the log message - - - - - - number of elements in the @fields array - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Log a message with structured data, accepting the data within a #GVariant. This -version is especially useful for use in other languages, via introspection. - -The only mandatory item in the @fields dictionary is the "MESSAGE" which must -contain the text shown to the user. - -The values in the @fields dictionary are likely to be of type String -(#G_VARIANT_TYPE_STRING). Array of bytes (#G_VARIANT_TYPE_BYTESTRING) is also -supported. In this case the message is handled as binary and will be forwarded -to the log writer as such. The size of the array should not be higher than -%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types -g_variant_print() will be used to convert the value into a string. - -For more details on its usage and about the parameters, see g_log_structured(). - - - - - - - log domain, usually %G_LOG_DOMAIN - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) -containing the key-value pairs of message data. - - - - - - Format a structured log message and output it to the default log destination -for the platform. On Linux, this is typically the systemd journal, falling -back to `stdout` or `stderr` if running from the terminal or if output is -being redirected to a file. - -Support for other platform-specific logging mechanisms may be added in -future. Distributors of GLib may modify this function to impose their own -(documented) platform-specific log writing policies. - -This is suitable for use as a #GLogWriterFunc, and is the default writer used -if no other is set using g_log_set_writer_func(). - -As with g_log_default_handler(), this function drops debug and informational -messages unless their log domain (or `all`) is listed in the space-separated -`G_MESSAGES_DEBUG` environment variable. - - - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key–value pairs of structured data forming - the log message - - - - - - number of elements in the @fields array - - - - user data passed to g_log_set_writer_func() - - - - - - Format a structured log message as a string suitable for outputting to the -terminal (or elsewhere). This will include the values of all fields it knows -how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the -documentation for g_log_structured()). It does not include values from -unknown fields. - -The returned string does **not** have a trailing new-line character. It is -encoded in the character set of the current locale, which is not necessarily -UTF-8. - - - string containing the formatted log message, in - the character set of the current locale - - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key–value pairs of structured data forming - the log message - - - - - - number of elements in the @fields array - - - - %TRUE to use ANSI color escape sequences when formatting the - message, %FALSE to not - - - - - - Check whether the given @output_fd file descriptor is a connection to the -systemd journal, or something else (like a log file or `stdout` or -`stderr`). - -Invalid file descriptors are accepted and return %FALSE, which allows for -the following construct without needing any additional error handling: -|[<!-- language="C" --> - is_journald = g_log_writer_is_journald (fileno (stderr)); -]| - - - %TRUE if @output_fd points to the journal, %FALSE otherwise - - - - - output file descriptor to check - - - - - - Format a structured log message and send it to the systemd journal as a set -of key–value pairs. All fields are sent to the journal, but if a field has -length zero (indicating program-specific data) then only its key will be -sent. - -This is suitable for use as a #GLogWriterFunc. - -If GLib has been compiled without systemd support, this function is still -defined, but will always return %G_LOG_WRITER_UNHANDLED. - - - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key–value pairs of structured data forming - the log message - - - - - - number of elements in the @fields array - - - - user data passed to g_log_set_writer_func() - - - - - - Format a structured log message and print it to either `stdout` or `stderr`, -depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages -are sent to `stdout`; all other log levels are sent to `stderr`. Only fields -which are understood by this function are included in the formatted string -which is printed. - -If the output stream supports ANSI color escape sequences, they will be used -in the output. - -A trailing new-line character is added to the log message when it is printed. - -This is suitable for use as a #GLogWriterFunc. - - - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - - - - - log level, either from #GLogLevelFlags, or a user-defined - level - - - - key–value pairs of structured data forming - the log message - - - - - - number of elements in the @fields array - - - - user data passed to g_log_set_writer_func() - - - - - - Check whether the given @output_fd file descriptor supports ANSI color -escape sequences. If so, they can safely be used when formatting log -messages. - - - %TRUE if ANSI color escapes are supported, %FALSE otherwise - - - - - output file descriptor to check - - - - - - Logs an error or debugging message. - -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for -details of the debugging options this provides. - -If g_log_default_handler() is used as the log handler function, a new-line -character will automatically be appended to @..., and need not be entered -manually. - -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). - - - - - - - the log domain, or %NULL for the default "" -application domain - - - - the log level - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - - - - - - - - - - - - - - - - - - - - - - Returns the global default main context. This is the main context -used for main loop functions when a main loop is not explicitly -specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). - - - the global default main context. - - - - - Gets the thread-default #GMainContext for this thread. Asynchronous -operations that want to be able to be run in contexts other than -the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) - -If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. - - - the thread-default #GMainContext, or -%NULL if the thread-default context is the global default context. - - - - - Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. - - - the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. - - - - - Returns the currently firing source for this thread. - - - The currently firing source or %NULL. - - - - - Returns the depth of the stack of calls to -g_main_context_dispatch() on any #GMainContext in the current thread. - That is, when called from the toplevel, it gives 0. When -called from within a callback from g_main_context_iteration() -(or g_main_loop_run(), etc.) it returns 1. When called from within -a callback to a recursive call to g_main_context_iteration(), -it returns 2. And so forth. - -This function is useful in a situation like the following: -Imagine an extremely simple "garbage collected" system. - -|[<!-- language="C" --> -static GList *free_list; - -gpointer -allocate_memory (gsize size) -{ - gpointer result = g_malloc (size); - free_list = g_list_prepend (free_list, result); - return result; -} - -void -free_allocated_memory (void) -{ - GList *l; - for (l = free_list; l; l = l->next); - g_free (l->data); - g_list_free (free_list); - free_list = NULL; - } - -[...] - -while (TRUE); - { - g_main_context_iteration (NULL, TRUE); - free_allocated_memory(); - } -]| - -This works from an application, however, if you want to do the same -thing from a library, it gets more difficult, since you no longer -control the main loop. You might think you can simply use an idle -function to make the call to free_allocated_memory(), but that -doesn't work, since the idle function could be called from a -recursive callback. This can be fixed by using g_main_depth() - -|[<!-- language="C" --> -gpointer -allocate_memory (gsize size) -{ - FreeListBlock *block = g_new (FreeListBlock, 1); - block->mem = g_malloc (size); - block->depth = g_main_depth (); - free_list = g_list_prepend (free_list, block); - return block->mem; -} - -void -free_allocated_memory (void) -{ - GList *l; - - int depth = g_main_depth (); - for (l = free_list; l; ); - { - GList *next = l->next; - FreeListBlock *block = l->data; - if (block->depth > depth) - { - g_free (block->mem); - g_free (block); - free_list = g_list_delete_link (free_list, l); - } - - l = next; - } - } -]| - -There is a temptation to use g_main_depth() to solve -problems with reentrancy. For instance, while waiting for data -to be received from the network in response to a menu item, -the menu item might be selected again. It might seem that -one could make the menu item's callback return immediately -and do nothing if g_main_depth() returns a value greater than 1. -However, this should be avoided since the user then sees selecting -the menu item do nothing. Furthermore, you'll find yourself adding -these checks all over your code, since there are doubtless many, -many things that the user could do. Instead, you can use the -following techniques: - -1. Use gtk_widget_set_sensitive() or modal dialogs to prevent - the user from interacting with elements while the main - loop is recursing. - -2. Avoid main loop recursion in situations where you can't handle - arbitrary callbacks. Instead, structure your code so that you - simply return to the main loop and then get called again when - there is more work to do. - - - The main loop recursion level in the current thread - - - - - Allocates @n_bytes bytes of memory. -If @n_bytes is 0 it returns %NULL. - - - a pointer to the allocated memory - - - - - the number of bytes to allocate - - - - - - Allocates @n_bytes bytes of memory, initialized to 0's. -If @n_bytes is 0 it returns %NULL. - - - a pointer to the allocated memory - - - - - the number of bytes to allocate - - - - - - This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - a pointer to the allocated memory - - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - a pointer to the allocated memory - - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - Collects the attributes of the element from the data passed to the -#GMarkupParser start_element function, dealing with common error -conditions and supporting boolean values. - -This utility function is not required to write a parser but can save -a lot of typing. - -The @element_name, @attribute_names, @attribute_values and @error -parameters passed to the start_element callback should be passed -unmodified to this function. - -Following these arguments is a list of "supported" attributes to collect. -It is an error to specify multiple attributes with the same name. If any -attribute not in the list appears in the @attribute_names array then an -unknown attribute error will result. - -The #GMarkupCollectType field allows specifying the type of collection -to perform and if a given attribute must appear or is optional. - -The attribute name is simply the name of the attribute to collect. - -The pointer should be of the appropriate type (see the descriptions -under #GMarkupCollectType) and may be %NULL in case a particular -attribute is to be allowed but ignored. - -This function deals with issuing errors for missing attributes -(of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes -(of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate -attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well -as parse errors for boolean-valued attributes (again of type -%G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE -will be returned and @error will be set as appropriate. - - - %TRUE if successful - - - - - the current tag name - - - - the attribute names - - - - the attribute values - - - - a pointer to a #GError or %NULL - - - - the #GMarkupCollectType of the first attribute - - - - the name of the first attribute - - - - a pointer to the storage location of the first attribute - (or %NULL), followed by more types names and pointers, ending - with %G_MARKUP_COLLECT_INVALID - - - - - - - - - - - Escapes text so that the markup parser will parse it verbatim. -Less than, greater than, ampersand, etc. are replaced with the -corresponding entities. This function would typically be used -when writing out a file to be parsed with the markup parser. - -Note that this function doesn't protect whitespace and line endings -from being processed according to the XML rules for normalization -of line endings and attribute values. - -Note also that this function will produce character references in -the range of &#x1; ... &#x1f; for all control sequences -except for tabstop, newline and carriage return. The character -references in this range are not valid XML 1.0, but they are -valid XML 1.1 and will be accepted by the GMarkup parser. - - - a newly allocated string with the escaped text - - - - - some valid UTF-8 text - - - - length of @text in bytes, or -1 if the text is nul-terminated - - - - - - Formats arguments according to @format, escaping -all string and character arguments in the fashion -of g_markup_escape_text(). This is useful when you -want to insert literal strings into XML-style markup -output, without having to worry that the strings -might themselves contain markup. - -|[<!-- language="C" --> -const char *store = "Fortnum & Mason"; -const char *item = "Tea"; -char *output; - -output = g_markup_printf_escaped ("<purchase>" - "<store>%s</store>" - "<item>%s</item>" - "</purchase>", - store, item); -]| - - - newly allocated result from formatting - operation. Free with g_free(). - - - - - printf() style format string - - - - the arguments to insert in the format string - - - - - - Formats the data in @args according to @format, escaping -all string and character arguments in the fashion -of g_markup_escape_text(). See g_markup_printf_escaped(). - - - newly allocated result from formatting - operation. Free with g_free(). - - - - - printf() style format string - - - - variable argument list, similar to vprintf() - - - - - - Checks whether the allocator used by g_malloc() is the system's -malloc implementation. If it returns %TRUE memory allocated with -malloc() can be used interchangeably with memory allocated using g_malloc(). -This function is useful for avoiding an extra copy of allocated memory returned -by a non-GLib-based API. - GLib always uses the system malloc, so this function always -returns %TRUE. - - - if %TRUE, malloc() and g_malloc() can be mixed. - - - - - GLib used to support some tools for memory profiling, but this -no longer works. There are many other useful tools for memory -profiling these days which can be used instead. - Use other memory profiling tools instead - - - - - - - This function used to let you override the memory allocation function. -However, its use was incompatible with the use of global constructors -in GLib and GIO, because those use the GLib allocators before main is -reached. Therefore this function is now deprecated and is just a stub. - This function now does nothing. Use other memory -profiling tools instead - - - - - - - table of memory allocation routines. - - - - - - Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is %NULL it returns %NULL. - - - a pointer to the newly-allocated copy of the memory, or %NULL if @mem - is %NULL. - - - - - the memory to copy. - - - - the number of bytes to copy. - - - - - - Copies a block of memory @len bytes long, from @src to @dest. -The source and destination areas may overlap. - Just use memmove(). - - - - the destination address to copy the bytes to. - - - the source address to copy the bytes from. - - - the number of bytes to copy. - - - - - Create a directory if it doesn't already exist. Create intermediate -parent directories as needed, too. - - - 0 if the directory already exists, or was successfully -created. Returns -1 if an error occurred, with errno set. - - - - - a pathname in the GLib file name encoding - - - - permissions to use for newly created directories - - - - - - Creates a temporary directory. See the mkdtemp() documentation -on most UNIX-like systems. - -The parameter is a string that should follow the rules for -mkdtemp() templates, i.e. contain the string "XXXXXX". -g_mkdtemp() is slightly more flexible than mkdtemp() in that the -sequence does not have to occur at the very end of the template. -The X string will be modified to form the name of a directory that -didn't exist. -The string should be in the GLib file name encoding. Most importantly, -on Windows it should be in UTF-8. - -If you are going to be creating a temporary directory inside the -directory returned by g_get_tmp_dir(), you might want to use -g_dir_make_tmp() instead. - - - A pointer to @tmpl, which has been - modified to hold the directory name. In case of errors, %NULL is - returned and %errno will be set. - - - - - template directory name - - - - - - Creates a temporary directory. See the mkdtemp() documentation -on most UNIX-like systems. - -The parameter is a string that should follow the rules for -mkdtemp() templates, i.e. contain the string "XXXXXX". -g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the -sequence does not have to occur at the very end of the template -and you can pass a @mode. The X string will be modified to form -the name of a directory that didn't exist. The string should be -in the GLib file name encoding. Most importantly, on Windows it -should be in UTF-8. - -If you are going to be creating a temporary directory inside the -directory returned by g_get_tmp_dir(), you might want to use -g_dir_make_tmp() instead. - - - A pointer to @tmpl, which has been - modified to hold the directory name. In case of errors, %NULL is - returned, and %errno will be set. - - - - - template directory name - - - - permissions to create the temporary directory with - - - - - - Opens a temporary file. See the mkstemp() documentation -on most UNIX-like systems. - -The parameter is a string that should follow the rules for -mkstemp() templates, i.e. contain the string "XXXXXX". -g_mkstemp() is slightly more flexible than mkstemp() in that the -sequence does not have to occur at the very end of the template. -The X string will be modified to form the name of a file that -didn't exist. The string should be in the GLib file name encoding. -Most importantly, on Windows it should be in UTF-8. - - - A file handle (as from open()) to the file - opened for reading and writing. The file is opened in binary - mode on platforms where there is a difference. The file handle - should be closed with close(). In case of errors, -1 is - returned and %errno will be set. - - - - - template filename - - - - - - Opens a temporary file. See the mkstemp() documentation -on most UNIX-like systems. - -The parameter is a string that should follow the rules for -mkstemp() templates, i.e. contain the string "XXXXXX". -g_mkstemp_full() is slightly more flexible than mkstemp() -in that the sequence does not have to occur at the very end of the -template and you can pass a @mode and additional @flags. The X -string will be modified to form the name of a file that didn't exist. -The string should be in the GLib file name encoding. Most importantly, -on Windows it should be in UTF-8. - - - A file handle (as from open()) to the file - opened for reading and writing. The file handle should be - closed with close(). In case of errors, -1 is returned - and %errno will be set. - - - - - template filename - - - - flags to pass to an open() call in addition to O_EXCL - and O_CREAT, which are passed automatically - - - - permissions to create the temporary file with - - - - - - Allocates @n_structs elements of type @struct_type. -The returned pointer is cast to a pointer to the given type. -If @n_structs is 0 it returns %NULL. -Care is taken to avoid overflow when calculating the size of the allocated block. - -Since the returned pointer is already casted to the right type, -it is normally unnecessary to cast it explicitly, and doing -so might hide memory allocation errors. - - - - the type of the elements to allocate - - - the number of elements to allocate - - - - - Allocates @n_structs elements of type @struct_type, initialized to 0's. -The returned pointer is cast to a pointer to the given type. -If @n_structs is 0 it returns %NULL. -Care is taken to avoid overflow when calculating the size of the allocated block. - -Since the returned pointer is already casted to the right type, -it is normally unnecessary to cast it explicitly, and doing -so might hide memory allocation errors. - - - - the type of the elements to allocate. - - - the number of elements to allocate. - - - - - Wraps g_alloca() in a more typesafe manner. - - - - Type of memory chunks to be allocated - - - Number of chunks to be allocated - - - - - Inserts a #GNode as the last child of the given parent. - - - - the #GNode to place the new #GNode under - - - the #GNode to insert - - - - - Inserts a new #GNode as the last child of the given parent. - - - - the #GNode to place the new #GNode under - - - the data for the new #GNode - - - - - Gets the first child of a #GNode. - - - - a #GNode - - - - - Inserts a new #GNode at the given position. - - - - the #GNode to place the new #GNode under - - - the position to place the new #GNode at. If position is -1, - the new #GNode is inserted as the last child of @parent - - - the data for the new #GNode - - - - - Inserts a new #GNode after the given sibling. - - - - the #GNode to place the new #GNode under - - - the sibling #GNode to place the new #GNode after - - - the data for the new #GNode - - - - - Inserts a new #GNode before the given sibling. - - - - the #GNode to place the new #GNode under - - - the sibling #GNode to place the new #GNode before - - - the data for the new #GNode - - - - - Gets the next sibling of a #GNode. - - - - a #GNode - - - - - Inserts a new #GNode as the first child of the given parent. - - - - the #GNode to place the new #GNode under - - - the data for the new #GNode - - - - - Gets the previous sibling of a #GNode. - - - - a #GNode - - - - - Converts a 32-bit integer value from network to host byte order. - - - - a 32-bit integer value in network byte order - - - - - Converts a 16-bit integer value from network to host byte order. - - - - a 16-bit integer value in network byte order - - - - - Set the pointer at the specified location to %NULL. - - - - - - - the memory address of the pointer. - - - - - - - - - - - Prompts the user with -`[E]xit, [H]alt, show [S]tack trace or [P]roceed`. -This function is intended to be used for debugging use only. -The following example shows how it can be used together with -the g_log() functions. - -|[<!-- language="C" --> -#include <glib.h> - -static void -log_handler (const gchar *log_domain, - GLogLevelFlags log_level, - const gchar *message, - gpointer user_data) -{ - g_log_default_handler (log_domain, log_level, message, user_data); - - g_on_error_query (MY_PROGRAM_NAME); -} - -int -main (int argc, char *argv[]) -{ - g_log_set_handler (MY_LOG_DOMAIN, - G_LOG_LEVEL_WARNING | - G_LOG_LEVEL_ERROR | - G_LOG_LEVEL_CRITICAL, - log_handler, - NULL); - ... -]| - -If "[E]xit" is selected, the application terminates with a call -to _exit(0). - -If "[S]tack" trace is selected, g_on_error_stack_trace() is called. -This invokes gdb, which attaches to the current process and shows -a stack trace. The prompt is then shown again. - -If "[P]roceed" is selected, the function returns. - -This function may cause different actions on non-UNIX platforms. - -On Windows consider using the `G_DEBUGGER` environment -variable (see [Running GLib Applications](glib-running.html)) and -calling g_on_error_stack_trace() instead. - - - - - - - the program name, needed by gdb for the "[S]tack trace" - option. If @prg_name is %NULL, g_get_prgname() is called to get - the program name (which will work correctly if gdk_init() or - gtk_init() has been called) - - - - - - Invokes gdb, which attaches to the current process and shows a -stack trace. Called by g_on_error_query() when the "[S]tack trace" -option is selected. You can get the current process's program name -with g_get_prgname(), assuming that you have called gtk_init() or -gdk_init(). - -This function may cause different actions on non-UNIX platforms. - -When running on Windows, this function is *not* called by -g_on_error_query(). If called directly, it will raise an -exception, which will crash the program. If the `G_DEBUGGER` environment -variable is set, a debugger will be invoked to attach and -handle that exception (see [Running GLib Applications](glib-running.html)). - - - - - - - the program name, needed by gdb for the "[S]tack trace" - option - - - - - - The first call to this routine by a process with a given #GOnce -struct calls @func with the given argument. Thereafter, subsequent -calls to g_once() with the same #GOnce struct do not call @func -again, but return the stored result of the first call. On return -from g_once(), the status of @once will be %G_ONCE_STATUS_READY. - -For example, a mutex or a thread-specific data key must be created -exactly once. In a threaded environment, calling g_once() ensures -that the initialization is serialized across multiple threads. - -Calling g_once() recursively on the same #GOnce struct in -@func will lead to a deadlock. - -|[<!-- language="C" --> - gpointer - get_debug_flags (void) - { - static GOnce my_once = G_ONCE_INIT; - - g_once (&my_once, parse_debug_flags, NULL); - - return my_once.retval; - } -]| - - - - a #GOnce structure - - - the #GThreadFunc function associated to @once. This function - is called only once, regardless of the number of times it and - its associated #GOnce struct are passed to g_once(). - - - data to be passed to @func - - - - - Function to be called when starting a critical initialization -section. The argument @location must point to a static -0-initialized variable that will be set to a value other than 0 at -the end of the initialization section. In combination with -g_once_init_leave() and the unique address @value_location, it can -be ensured that an initialization section will be executed only once -during a program's life time, and that concurrent threads are -blocked until initialization completed. To be used in constructs -like this: - -|[<!-- language="C" --> - static gsize initialization_value = 0; - - if (g_once_init_enter (&initialization_value)) - { - gsize setup_value = 42; // initialization code here - - g_once_init_leave (&initialization_value, setup_value); - } - - // use initialization_value here -]| - - - %TRUE if the initialization section should be entered, - %FALSE and blocks otherwise - - - - - location of a static initializable variable - containing 0 - - - - - - Counterpart to g_once_init_enter(). Expects a location of a static -0-initialized initialization variable, and an initialization value -other than 0. Sets the variable to the initialization value, and -releases concurrent threads blocking in g_once_init_enter() on this -initialization variable. - - - - - - - location of a static initializable variable - containing 0 - - - - new non-0 value for *@value_location - - - - - - - - - - - Parses a string containing debugging options -into a %guint containing bit flags. This is used -within GDK and GTK+ to parse the debug options passed on the -command line or through environment variables. - -If @string is equal to "all", all flags are set. Any flags -specified along with "all" in @string are inverted; thus, -"all,foo,bar" or "foo,bar,all" sets all flags except those -corresponding to "foo" and "bar". - -If @string is equal to "help", all the available keys in @keys -are printed out to standard error. - - - the combined set of bit flags. - - - - - a list of debug options separated by colons, spaces, or -commas, or %NULL. - - - - pointer to an array of #GDebugKey which associate - strings with bit flags. - - - - - - the number of #GDebugKeys in the array. - - - - - - Gets the last component of the filename. - -If @file_name ends with a directory separator it gets the component -before the last slash. If @file_name consists only of directory -separators (and on Windows, possibly a drive letter), a single -separator is returned. If @file_name is empty, it gets ".". - - - a newly allocated string containing the last - component of the filename - - - - - the name of the file - - - - - - Gets the directory components of a file name. For example, the directory -component of `/usr/bin/test` is `/usr/bin`. The directory component of `/` -is `/`. - -If the file name has no directory components "." is returned. -The returned string should be freed when no longer needed. - - - the directory components of the file - - - - - the name of the file - - - - - - Returns %TRUE if the given @file_name is an absolute file name. -Note that this is a somewhat vague concept on Windows. - -On POSIX systems, an absolute file name is well-defined. It always -starts from the single root directory. For example "/usr/local". - -On Windows, the concepts of current drive and drive-specific -current directory introduce vagueness. This function interprets as -an absolute file name one that either begins with a directory -separator such as "\Users\tml" or begins with the root on a drive, -for example "C:\Windows". The first case also includes UNC paths -such as "\\\\myserver\docs\foo". In all cases, either slashes or -backslashes are accepted. - -Note that a file name relative to the current drive root does not -truly specify a file uniquely over time and across processes, as -the current drive is a per-process value and can be changed. - -File names relative the current directory on some specific drive, -such as "D:foo/bar", are not interpreted as absolute by this -function, but they obviously are not relative to the normal current -directory as returned by getcwd() or g_get_current_dir() -either. Such paths should be avoided, or need to be handled using -Windows-specific code. - - - %TRUE if @file_name is absolute - - - - - a file name - - - - - - Returns a pointer into @file_name after the root component, -i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name -is not an absolute path it returns %NULL. - - - a pointer into @file_name after the - root component - - - - - a file name - - - - - - Matches a string against a compiled pattern. Passing the correct -length of the string given is mandatory. The reversed string can be -omitted by passing %NULL, this is more efficient if the reversed -version of the string to be matched is not at hand, as -g_pattern_match() will only construct it if the compiled pattern -requires reverse matches. - -Note that, if the user code will (possibly) match a string against a -multitude of patterns containing wildcards, chances are high that -some patterns will require a reversed string. In this case, it's -more efficient to provide the reversed string to avoid multiple -constructions thereof in the various calls to g_pattern_match(). - -Note also that the reverse of a UTF-8 encoded string can in general -not be obtained by g_strreverse(). This works only if the string -does not contain any multibyte characters. GLib offers the -g_utf8_strreverse() function to reverse UTF-8 encoded strings. - - - %TRUE if @string matches @pspec - - - - - a #GPatternSpec - - - - the length of @string (in bytes, i.e. strlen(), - not g_utf8_strlen()) - - - - the UTF-8 encoded string to match - - - - the reverse of @string or %NULL - - - - - - Matches a string against a pattern given as a string. If this -function is to be called in a loop, it's more efficient to compile -the pattern once with g_pattern_spec_new() and call -g_pattern_match_string() repeatedly. - - - %TRUE if @string matches @pspec - - - - - the UTF-8 encoded pattern - - - - the UTF-8 encoded string to match - - - - - - Matches a string against a compiled pattern. If the string is to be -matched against more than one pattern, consider using -g_pattern_match() instead while supplying the reversed string. - - - %TRUE if @string matches @pspec - - - - - a #GPatternSpec - - - - the UTF-8 encoded string to match - - - - - - This is equivalent to g_bit_lock, but working on pointers (or other -pointer-sized values). - -For portability reasons, you may only lock on the bottom 32 bits of -the pointer. - - - - - - - a pointer to a #gpointer-sized value - - - - a bit value between 0 and 31 - - - - - - This is equivalent to g_bit_trylock, but working on pointers (or -other pointer-sized values). - -For portability reasons, you may only lock on the bottom 32 bits of -the pointer. - - - %TRUE if the lock was acquired - - - - - a pointer to a #gpointer-sized value - - - - a bit value between 0 and 31 - - - - - - This is equivalent to g_bit_unlock, but working on pointers (or other -pointer-sized values). - -For portability reasons, you may only lock on the bottom 32 bits of -the pointer. - - - - - - - a pointer to a #gpointer-sized value - - - - a bit value between 0 and 31 - - - - - - Polls @fds, as with the poll() system call, but portably. (On -systems that don't have poll(), it is emulated using select().) -This is used internally by #GMainContext, but it can be called -directly if you need to block until a file descriptor is ready, but -don't want to run the full main loop. - -Each element of @fds is a #GPollFD describing a single file -descriptor to poll. The @fd field indicates the file descriptor, -and the @events field indicates the events to poll for. On return, -the @revents fields will be filled with the events that actually -occurred. - -On POSIX systems, the file descriptors in @fds can be any sort of -file descriptor, but the situation is much more complicated on -Windows. If you need to use g_poll() in code that has to run on -Windows, the easiest solution is to construct all of your -#GPollFDs with g_io_channel_win32_make_pollfd(). - - - the number of entries in @fds whose @revents fields -were filled in, or 0 if the operation timed out, or -1 on error or -if the call was interrupted. - - - - - file descriptors to poll - - - - the number of file descriptors in @fds - - - - amount of time to wait, in milliseconds, or -1 to wait forever - - - - - - Formats a string according to @format and prefix it to an existing -error message. If @err is %NULL (ie: no error variable) then do -nothing. - -If *@err is %NULL (ie: an error variable is present but there is no -error condition) then also do nothing. - - - - - - - a return location for a #GError - - - - printf()-style format string - - - - arguments to @format - - - - - - Outputs a formatted message via the print handler. -The default print handler simply outputs the message to stdout, without -appending a trailing new-line character. Typically, @format should end with -its own new-line character. - -g_print() should not be used from within libraries for debugging -messages, since it may be redirected by applications to special -purpose message windows or even files. Instead, libraries should -use g_log(), g_log_structured(), or the convenience macros g_message(), -g_warning() and g_error(). - - - - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Outputs a formatted message via the error message handler. -The default handler simply outputs the message to stderr, without appending -a trailing new-line character. Typically, @format should end with its own -new-line character. - -g_printerr() should not be used from within libraries. -Instead g_log() or g_log_structured() should be used, or the convenience -macros g_message(), g_warning() and g_error(). - - - - - - - the message format. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - An implementation of the standard printf() function which supports -positional parameters, as specified in the Single Unix Specification. - -As with the standard printf(), this does not automatically append a trailing -new-line character to the message, so typically @format should end with its -own new-line character. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the arguments to insert in the output. - - - - - - Calculates the maximum space needed to store the output -of the sprintf() function. - - - the maximum space needed to store the formatted string - - - - - the format string. See the printf() documentation - - - - the parameters to be inserted into the format string - - - - - - If @dest is %NULL, free @src; otherwise, moves @src into *@dest. -The error variable @dest points to must be %NULL. - -@src must be non-%NULL. - -Note that @src is no longer valid after this call. If you want -to keep using the same GError*, you need to set it to %NULL -after calling this function on it. - - - - - - - error return location - - - - error to move into the return location - - - - - - If @dest is %NULL, free @src; otherwise, moves @src into *@dest. -*@dest must be %NULL. After the move, add a prefix as with -g_prefix_error(). - - - - - - - error return location - - - - error to move into the return location - - - - printf()-style format string - - - - arguments to @format - - - - - - Checks whether @needle exists in @haystack. If the element is found, %TRUE is -returned and the element’s index is returned in @index_ (if non-%NULL). -Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists -multiple times in @haystack, the index of the first instance is returned. - -This does pointer comparisons only. If you want to use more complex equality -checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). - - - %TRUE if @needle is one of the elements of @haystack - - - - - pointer array to be searched - - - - - - pointer to look for - - - - return location for the index of - the element, if found - - - - - - Checks whether @needle exists in @haystack, using the given @equal_func. -If the element is found, %TRUE is returned and the element’s index is -returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ -is undefined. If @needle exists multiple times in @haystack, the index of -the first instance is returned. - -@equal_func is called with the element from the array as its first parameter, -and @needle as its second parameter. If @equal_func is %NULL, pointer -equality is used. - - - %TRUE if @needle is one of the elements of @haystack - - - - - pointer array to be searched - - - - - - pointer to look for - - - - the function to call for each element, which should - return %TRUE when the desired element is found; or %NULL to use pointer - equality - - - - return location for the index of - the element, if found - - - - - - Returns the pointer at the given index of the pointer array. - -This does not perform bounds checking on the given @index_, -so you are responsible for checking it against the array length. - - - - a #GPtrArray - - - the index of the pointer to return - - - - - This is just like the standard C qsort() function, but -the comparison routine accepts a user data argument. - -This is guaranteed to be a stable sort since version 2.32. - - - - - - - start of array to sort - - - - elements in the array - - - - size of each element - - - - function to compare elements - - - - data to pass to @compare_func - - - - - - Gets the #GQuark identifying the given (static) string. If the -string does not currently have an associated #GQuark, a new #GQuark -is created, linked to the given string. - -Note that this function is identical to g_quark_from_string() except -that if a new #GQuark is created the string itself is used rather -than a copy. This saves memory, but can only be used if the string -will continue to exist until the program terminates. It can be used -with statically allocated strings in the main program, but not with -statically allocated memory in dynamically loaded modules, if you -expect to ever unload the module again (e.g. do not use this -function in GTK+ theme engines). - -This function must not be used before library constructors have finished -running. In particular, this means it cannot be used to initialize global -variables in C++. - - - the #GQuark identifying the string, or 0 if @string is %NULL - - - - - a string - - - - - - Gets the #GQuark identifying the given string. If the string does -not currently have an associated #GQuark, a new #GQuark is created, -using a copy of the string. - -This function must not be used before library constructors have finished -running. In particular, this means it cannot be used to initialize global -variables in C++. - - - the #GQuark identifying the string, or 0 if @string is %NULL - - - - - a string - - - - - - Gets the string associated with the given #GQuark. - - - the string associated with the #GQuark - - - - - a #GQuark. - - - - - - Gets the #GQuark associated with the given string, or 0 if string is -%NULL or it has no associated #GQuark. - -If you want the GQuark to be created if it doesn't already exist, -use g_quark_from_string() or g_quark_from_static_string(). - -This function must not be used before library constructors have finished -running. - - - the #GQuark associated with the string, or 0 if @string is - %NULL or there is no #GQuark associated with it - - - - - a string - - - - - - Returns a random #gboolean from @rand_. -This corresponds to an unbiased coin toss. - - - - a #GRand - - - - - Returns a random #gdouble equally distributed over the range [0..1). - - - a random number - - - - - Returns a random #gdouble equally distributed over the range -[@begin..@end). - - - a random number - - - - - lower closed bound of the interval - - - - upper open bound of the interval - - - - - - Return a random #guint32 equally distributed over the range -[0..2^32-1]. - - - a random number - - - - - Returns a random #gint32 equally distributed over the range -[@begin..@end-1]. - - - a random number - - - - - lower closed bound of the interval - - - - upper open bound of the interval - - - - - - Sets the seed for the global random number generator, which is used -by the g_random_* functions, to @seed. - - - - - - - a value to reinitialize the global random number generator - - - - - - Acquires a reference on the data pointed by @mem_block. - - - a pointer to the data, - with its reference count increased - - - - - a pointer to reference counted data - - - - - - Allocates @block_size bytes of memory, and adds reference -counting semantics to it. - -The data will be freed when its reference count drops to -zero. - -The allocated data is guaranteed to be suitably aligned for any -built-in type. - - - a pointer to the allocated memory - - - - - the size of the allocation, must be greater than 0 - - - - - - Allocates @block_size bytes of memory, and adds reference -counting semantics to it. - -The contents of the returned data is set to zero. - -The data will be freed when its reference count drops to -zero. - -The allocated data is guaranteed to be suitably aligned for any -built-in type. - - - a pointer to the allocated memory - - - - - the size of the allocation, must be greater than 0 - - - - - - Allocates a new block of data with reference counting -semantics, and copies @block_size bytes of @mem_block -into it. - - - a pointer to the allocated - memory - - - - - the number of bytes to copy, must be greater than 0 - - - - the memory to copy - - - - - - Retrieves the size of the reference counted data pointed by @mem_block. - - - the size of the data, in bytes - - - - - a pointer to reference counted data - - - - - - A convenience macro to allocate reference counted data with -the size of the given @type. - -This macro calls g_rc_box_alloc() with `sizeof (@type)` and -casts the returned pointer to a pointer of the given @type, -avoiding a type cast in the source code. - - - - the type to allocate, typically a structure name - - - - - A convenience macro to allocate reference counted data with -the size of the given @type, and set its contents to zero. - -This macro calls g_rc_box_alloc0() with `sizeof (@type)` and -casts the returned pointer to a pointer of the given @type, -avoiding a type cast in the source code. - - - - the type to allocate, typically a structure name - - - - - Releases a reference on the data pointed by @mem_block. - -If the reference was the last one, it will free the -resources allocated for @mem_block. - - - - - - - a pointer to reference counted data - - - - - - Releases a reference on the data pointed by @mem_block. - -If the reference was the last one, it will call @clear_func -to clear the contents of @mem_block, and then will free the -resources allocated for @mem_block. - - - - - - - a pointer to reference counted data - - - - a function to call when clearing the data - - - - - - Reallocates the memory pointed to by @mem, so that it now has space for -@n_bytes bytes of memory. It returns the new address of the memory, which may -have been moved. @mem may be %NULL, in which case it's considered to -have zero-length. @n_bytes may be 0, in which case %NULL will be returned -and @mem will be freed unless it is %NULL. - - - the new address of the allocated memory - - - - - the memory to reallocate - - - - new size of the memory in bytes - - - - - - This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - the new address of the allocated memory - - - - - the memory to reallocate - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - Compares the current value of @rc with @val. - - - %TRUE if the reference count is the same - as the given value - - - - - the address of a reference count variable - - - - the value to compare - - - - - - Decreases the reference count. - - - %TRUE if the reference count reached 0, and %FALSE otherwise - - - - - the address of a reference count variable - - - - - - Increases the reference count. - - - - - - - the address of a reference count variable - - - - - - Initializes a reference count variable. - - - - - - - the address of a reference count variable - - - - - - Acquires a reference on a string. - - - the given string, with its reference count increased - - - - - a reference counted string - - - - - - Retrieves the length of @str. - - - the length of the given string, in bytes - - - - - a reference counted string - - - - - - Creates a new reference counted string and copies the contents of @str -into it. - - - the newly created reference counted string - - - - - a NUL-terminated string - - - - - - Creates a new reference counted string and copies the content of @str -into it. - -If you call this function multiple times with the same @str, or with -the same contents of @str, it will return a new reference, instead of -creating a new string. - - - the newly created reference - counted string, or a new reference to an existing string - - - - - a NUL-terminated string - - - - - - Creates a new reference counted string and copies the contents of @str -into it, up to @len bytes. - -Since this function does not stop at nul bytes, it is the caller's -responsibility to ensure that @str has at least @len addressable bytes. - - - the newly created reference counted string - - - - - a string - - - - length of @str to use, or -1 if @str is nul-terminated - - - - - - Releases a reference on a string; if it was the last reference, the -resources allocated by the string are freed as well. - - - - - - - a reference counted string - - - - - - Checks whether @replacement is a valid replacement string -(see g_regex_replace()), i.e. that all escape sequences in -it are valid. - -If @has_references is not %NULL then @replacement is checked -for pattern references. For instance, replacement text 'foo\n' -does not contain references and may be evaluated without information -about actual match, but '\0\1' (whole match followed by first -subpattern) requires valid #GMatchInfo object. - - - whether @replacement is a valid replacement string - - - - - the replacement string - - - - location to store information about - references in @replacement or %NULL - - - - - - - - - - - Escapes the nul characters in @string to "\x00". It can be used -to compile a regex with embedded nul characters. - -For completeness, @length can be -1 for a nul-terminated string. -In this case the output string will be of course equal to @string. - - - a newly-allocated escaped string - - - - - the string to escape - - - - the length of @string - - - - - - Escapes the special characters used for regular expressions -in @string, for instance "a.b*c" becomes "a\.b\*c". This -function is useful to dynamically generate regular expressions. - -@string can contain nul characters that are replaced with "\0", -in this case remember to specify the correct length of @string -in @length. - - - a newly-allocated escaped string - - - - - the string to escape - - - - - - the length of @string, in bytes, or -1 if @string is nul-terminated - - - - - - Scans for a match in @string for @pattern. - -This function is equivalent to g_regex_match() but it does not -require to compile the pattern with g_regex_new(), avoiding some -lines of code when you need just to do a match without extracting -substrings, capture counts, and so on. - -If this function is to be called on the same @pattern more than -once, it's more efficient to compile the pattern once with -g_regex_new() and then use g_regex_match(). - - - %TRUE if the string matched, %FALSE otherwise - - - - - the regular expression - - - - the string to scan for matches - - - - compile options for the regular expression, or 0 - - - - match options, or 0 - - - - - - Breaks the string on the pattern, and returns an array of -the tokens. If the pattern contains capturing parentheses, -then the text for each of the substrings will also be returned. -If the pattern does not match anywhere in the string, then the -whole string is returned as the first token. - -This function is equivalent to g_regex_split() but it does -not require to compile the pattern with g_regex_new(), avoiding -some lines of code when you need just to do a split without -extracting substrings, capture counts, and so on. - -If this function is to be called on the same @pattern more than -once, it's more efficient to compile the pattern once with -g_regex_new() and then use g_regex_split(). - -As a special case, the result of splitting the empty string "" -is an empty vector, not a vector containing a single string. -The reason for this special case is that being able to represent -an empty vector is typically more useful than consistent handling -of empty elements. If you do need to represent empty elements, -you'll need to check for the empty string before calling this -function. - -A pattern that can match empty strings splits @string into -separate characters wherever it matches the empty string between -characters. For example splitting "ab c" using as a separator -"\s*", you will get "a", "b" and "c". - - - a %NULL-terminated array of strings. Free -it using g_strfreev() - - - - - - - the regular expression - - - - the string to scan for matches - - - - compile options for the regular expression, or 0 - - - - match options, or 0 - - - - - - Resets the cache used for g_get_user_special_dir(), so -that the latest on-disk version is used. Call this only -if you just changed the data on disk yourself. - -Due to thread safety issues this may cause leaking of strings -that were previously returned from g_get_user_special_dir() -that can't be freed. We ensure to only leak the data for -the directories that actually changed value though. - - - - - - - Reallocates the memory pointed to by @mem, so that it now has space for -@n_structs elements of type @struct_type. It returns the new address of -the memory, which may have been moved. -Care is taken to avoid overflow when calculating the size of the allocated block. - - - - the type of the elements to allocate - - - the currently allocated memory - - - the number of elements to allocate - - - - - - - - - - - - Internal function used to print messages from the public g_return_if_fail() -and g_return_val_if_fail() macros. - - - - - - - log domain - - - - function containing the assertion - - - - expression which failed - - - - - - - - - - - - - - - - - - - - - - A wrapper for the POSIX rmdir() function. The rmdir() function -deletes a directory from the filesystem. - -See your C library manual for more details about how rmdir() works -on your system. - - - 0 if the directory was successfully removed, -1 if an error - occurred - - - - - a pathname in the GLib file name encoding - (UTF-8 on Windows) - - - - - - Adds a symbol to the default scope. - Use g_scanner_scope_add_symbol() instead. - - - - a #GScanner - - - the symbol to add - - - the value of the symbol - - - - - Calls a function for each symbol in the default scope. - Use g_scanner_scope_foreach_symbol() instead. - - - - a #GScanner - - - the function to call with each symbol - - - data to pass to the function - - - - - There is no reason to use this macro, since it does nothing. - This macro does nothing. - - - - a #GScanner - - - - - Removes a symbol from the default scope. - Use g_scanner_scope_remove_symbol() instead. - - - - a #GScanner - - - the symbol to remove - - - - - There is no reason to use this macro, since it does nothing. - This macro does nothing. - - - - a #GScanner - - - - - Returns the data that @iter points to. - - - the data that @iter points to - - - - - a #GSequenceIter - - - - - - Inserts a new item just before the item pointed to by @iter. - - - an iterator pointing to the new item - - - - - a #GSequenceIter - - - - the data for the new item - - - - - - Moves the item pointed to by @src to the position indicated by @dest. -After calling this function @dest will point to the position immediately -after @src. It is allowed for @src and @dest to point into different -sequences. - - - - - - - a #GSequenceIter pointing to the item to move - - - - a #GSequenceIter pointing to the position to which - the item is moved - - - - - - Inserts the (@begin, @end) range at the destination pointed to by @dest. -The @begin and @end iters must point into the same sequence. It is -allowed for @dest to point to a different sequence than the one pointed -into by @begin and @end. - -If @dest is %NULL, the range indicated by @begin and @end is -removed from the sequence. If @dest points to a place within -the (@begin, @end) range, the range does not move. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Finds an iterator somewhere in the range (@begin, @end). This -iterator will be close to the middle of the range, but is not -guaranteed to be exactly in the middle. - -The @begin and @end iterators must both point to the same sequence -and @begin must come before or be equal to @end in the sequence. - - - a #GSequenceIter pointing somewhere in the - (@begin, @end) range - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Removes the item pointed to by @iter. It is an error to pass the -end iterator to this function. - -If the sequence has a data destroy function associated with it, this -function is called on the data for the removed item. - - - - - - - a #GSequenceIter - - - - - - Removes all items in the (@begin, @end) range. - -If the sequence has a data destroy function associated with it, this -function is called on the data for the removed items. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Changes the data for the item pointed to by @iter to be @data. If -the sequence has a data destroy function associated with it, that -function is called on the existing data that @iter pointed to. - - - - - - - a #GSequenceIter - - - - new data for the item - - - - - - Swaps the items pointed to by @a and @b. It is allowed for @a and @b -to point into difference sequences. - - - - - - - a #GSequenceIter - - - - a #GSequenceIter - - - - - - Sets a human-readable name for the application. This name should be -localized if possible, and is intended for display to the user. -Contrast with g_set_prgname(), which sets a non-localized name. -g_set_prgname() will be called automatically by gtk_init(), -but g_set_application_name() will not. - -Note that for thread safety reasons, this function can only -be called once. - -The application name will be used in contexts such as error messages, -or when displaying an application's name in the task list. - - - - - - - localized name of the application - - - - - - Does nothing if @err is %NULL; if @err is non-%NULL, then *@err -must be %NULL. A new #GError is created and assigned to *@err. - - - - - - - a return location for a #GError - - - - error domain - - - - error code - - - - printf()-style format - - - - args for @format - - - - - - Does nothing if @err is %NULL; if @err is non-%NULL, then *@err -must be %NULL. A new #GError is created and assigned to *@err. -Unlike g_set_error(), @message is not a printf()-style format string. -Use this function if @message contains text you don't have control over, -that could include printf() escape sequences. - - - - - - - a return location for a #GError - - - - error domain - - - - error code - - - - error message - - - - - - Sets the name of the program. This name should not be localized, -in contrast to g_set_application_name(). - -If you are using #GApplication the program name is set in -g_application_run(). In case of GDK or GTK+ it is set in -gdk_init(), which is called by gtk_init() and the -#GtkApplication::startup handler. The program name is found by -taking the last component of @argv[0]. - -Note that for thread-safety reasons this function can only be called once. - - - - - - - the name of the program. - - - - - - Sets the print handler. - -Any messages passed to g_print() will be output via -the new handler. The default handler simply outputs -the message to stdout. By providing your own handler -you can redirect the output, to a GTK+ widget or a -log file for example. - - - the old print handler - - - - - the new print handler - - - - - - Sets the handler for printing error messages. - -Any messages passed to g_printerr() will be output via -the new handler. The default handler simply outputs the -message to stderr. By providing your own handler you can -redirect the output, to a GTK+ widget or a log file for -example. - - - the old error message handler - - - - - the new error message handler - - - - - - Sets an environment variable. On UNIX, both the variable's name and -value can be arbitrary byte strings, except that the variable's name -cannot contain '='. On Windows, they should be in UTF-8. - -Note that on some systems, when variables are overwritten, the memory -used for the previous variables and its value isn't reclaimed. - -You should be mindful of the fact that environment variable handling -in UNIX is not thread-safe, and your program may crash if one thread -calls g_setenv() while another thread is calling getenv(). (And note -that many functions, such as gettext(), call getenv() internally.) -This function is only safe to use at the very start of your program, -before creating any other threads (or creating objects that create -worker threads of their own). - -If you need to set up the environment for a child process, you can -use g_get_environ() to get an environment array, modify that with -g_environ_setenv() and g_environ_unsetenv(), and then pass that -array directly to execvpe(), g_spawn_async(), or the like. - - - %FALSE if the environment variable couldn't be set. - - - - - the environment variable to set, must not - contain '='. - - - - the value for to set the variable to. - - - - whether to change the variable if it already exists. - - - - - - - - - - - Parses a command line into an argument vector, in much the same way -the shell would, but without many of the expansions the shell would -perform (variable expansion, globs, operators, filename expansion, -etc. are not supported). The results are defined to be the same as -those you would get from a UNIX98 /bin/sh, as long as the input -contains none of the unsupported shell expansions. If the input -does contain such expansions, they are passed through -literally. Possible errors are those from the #G_SHELL_ERROR -domain. Free the returned vector with g_strfreev(). - - - %TRUE on success, %FALSE if error set - - - - - command line to parse - - - - return location for number of args - - - - - return location for array of args - - - - - - - - Quotes a string so that the shell (/bin/sh) will interpret the -quoted string to mean @unquoted_string. If you pass a filename to -the shell, for example, you should first quote it with this -function. The return value must be freed with g_free(). The -quoting style used is undefined (single or double quotes may be -used). - - - quoted string - - - - - a literal string - - - - - - Unquotes a string as the shell (/bin/sh) would. Only handles -quotes; if a string contains file globs, arithmetic operators, -variables, backticks, redirections, or other special-to-the-shell -features, the result will be different from the result a real shell -would produce (the variables, backticks, etc. will be passed -through literally instead of being expanded). This function is -guaranteed to succeed if applied to the result of -g_shell_quote(). If it fails, it returns %NULL and sets the -error. The @quoted_string need not actually contain quoted or -escaped text; g_shell_unquote() simply goes through the string and -unquotes/unescapes anything that the shell would. Both single and -double quotes are handled, as are escapes including escaped -newlines. The return value must be freed with g_free(). Possible -errors are in the #G_SHELL_ERROR domain. - -Shell quoting rules are a bit strange. Single quotes preserve the -literal string exactly. escape sequences are not allowed; not even -\' - if you want a ' in the quoted text, you have to do something -like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to -be escaped with backslash. Otherwise double quotes preserve things -literally. - - - an unquoted string - - - - - shell-quoted string - - - - - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #gsize destination - - - the #gsize left operand - - - the #gsize right operand - - - - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #gsize destination - - - the #gsize left operand - - - the #gsize right operand - - - - - Allocates a block of memory from the slice allocator. -The block address handed out can be expected to be aligned -to at least 1 * sizeof (void*), -though in general slices are 2 * sizeof (void*) bytes aligned, -if a malloc() fallback implementation is used instead, -the alignment may be reduced in a libc dependent fashion. -Note that the underlying slice allocation mechanism can -be changed with the [`G_SLICE=always-malloc`][G_SLICE] -environment variable. - - - a pointer to the allocated memory block, which will be %NULL if and - only if @mem_size is 0 - - - - - the number of bytes to allocate - - - - - - Allocates a block of memory via g_slice_alloc() and initializes -the returned memory to 0. Note that the underlying slice allocation -mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] -environment variable. - - - a pointer to the allocated block, which will be %NULL if and only - if @mem_size is 0 - - - - - the number of bytes to allocate - - - - - - Allocates a block of memory from the slice allocator -and copies @block_size bytes into it from @mem_block. - -@mem_block must be non-%NULL if @block_size is non-zero. - - - a pointer to the allocated memory block, which will be %NULL if and - only if @mem_size is 0 - - - - - the number of bytes to allocate - - - - the memory to copy - - - - - - A convenience macro to duplicate a block of memory using -the slice allocator. - -It calls g_slice_copy() with `sizeof (@type)` -and casts the returned pointer to a pointer of the given type, -avoiding a type cast in the source code. -Note that the underlying slice allocation mechanism can -be changed with the [`G_SLICE=always-malloc`][G_SLICE] -environment variable. - -This can never return %NULL. - - - - the type to duplicate, typically a structure name - - - the memory to copy into the allocated block - - - - - A convenience macro to free a block of memory that has -been allocated from the slice allocator. - -It calls g_slice_free1() using `sizeof (type)` -as the block size. -Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see -[`G_SLICE`][G_SLICE] for related debugging options. - -If @mem is %NULL, this macro does nothing. - - - - the type of the block to free, typically a structure name - - - a pointer to the block to free - - - - - Frees a block of memory. - -The memory must have been allocated via g_slice_alloc() or -g_slice_alloc0() and the @block_size has to match the size -specified upon allocation. Note that the exact release behaviour -can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment -variable, also see [`G_SLICE`][G_SLICE] for related debugging options. - -If @mem_block is %NULL, this function does nothing. - - - - - - - the size of the block - - - - a pointer to the block to free - - - - - - Frees a linked list of memory blocks of structure type @type. -The memory blocks must be equal-sized, allocated via -g_slice_alloc() or g_slice_alloc0() and linked together by -a @next pointer (similar to #GSList). The name of the -@next field in @type is passed as third argument. -Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see -[`G_SLICE`][G_SLICE] for related debugging options. - -If @mem_chain is %NULL, this function does nothing. - - - - the type of the @mem_chain blocks - - - a pointer to the first block of the chain - - - the field name of the next pointer in @type - - - - - Frees a linked list of memory blocks of structure type @type. - -The memory blocks must be equal-sized, allocated via -g_slice_alloc() or g_slice_alloc0() and linked together by a -@next pointer (similar to #GSList). The offset of the @next -field in each block is passed as third argument. -Note that the exact release behaviour can be changed with the -[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see -[`G_SLICE`][G_SLICE] for related debugging options. - -If @mem_chain is %NULL, this function does nothing. - - - - - - - the size of the blocks - - - - a pointer to the first block of the chain - - - - the offset of the @next field in the blocks - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A convenience macro to allocate a block of memory from the -slice allocator. - -It calls g_slice_alloc() with `sizeof (@type)` and casts the -returned pointer to a pointer of the given type, avoiding a type -cast in the source code. Note that the underlying slice allocation -mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] -environment variable. - -This can never return %NULL as the minimum allocation size from -`sizeof (@type)` is 1 byte. - - - - the type to allocate, typically a structure name - - - - - A convenience macro to allocate a block of memory from the -slice allocator and set the memory to 0. - -It calls g_slice_alloc0() with `sizeof (@type)` -and casts the returned pointer to a pointer of the given type, -avoiding a type cast in the source code. -Note that the underlying slice allocation mechanism can -be changed with the [`G_SLICE=always-malloc`][G_SLICE] -environment variable. - -This can never return %NULL as the minimum allocation size from -`sizeof (@type)` is 1 byte. - - - - the type to allocate, typically a structure name - - - - - - - - - - - - - - - - - - - A convenience macro to get the next element in a #GSList. -Note that it is considered perfectly acceptable to access -@slist->next directly. - - - - an element in a #GSList. - - - - - A safer form of the standard sprintf() function. The output is guaranteed -to not exceed @n characters (including the terminating nul character), so -it is easy to ensure that a buffer overflow cannot occur. - -See also g_strdup_printf(). - -In versions of GLib prior to 1.2.3, this function may return -1 if the -output was truncated, and the truncated string may not be nul-terminated. -In versions prior to 1.3.12, this function returns the length of the output -string. - -The return value of g_snprintf() conforms to the snprintf() -function as standardized in ISO C99. Note that this is different from -traditional snprintf(), which returns the length of the output string. - -The format string may contain positional parameters, as specified in -the Single Unix Specification. - - - the number of bytes which would be produced if the buffer - was large enough. - - - - - the buffer to hold the output. - - - - the maximum number of bytes to produce (including the - terminating nul character). - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the arguments to insert in the output. - - - - - - Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. - -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). - -It is a programmer error to attempt to remove a non-existent source. - -More specifically: source IDs can be reissued after a source has been -destroyed and therefore it is never valid to use this function with a -source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the -idle may already have run and been removed by the time this function -is called on its (now invalid) source ID. This source ID may have -been reissued, leading to the operation being performed against the -wrong source. - - - For historical reasons, this function always returns %TRUE - - - - - the ID of the source to remove. - - - - - - Removes a source from the default main loop context given the -source functions and user data. If multiple sources exist with the -same source functions and user data, only one will be destroyed. - - - %TRUE if a source was found and removed. - - - - - The @source_funcs passed to g_source_new() - - - - the user data for the callback - - - - - - Removes a source from the default main loop context given the user -data for the callback. If multiple sources exist with the same user -data, only one will be destroyed. - - - %TRUE if a source was found and removed. - - - - - the user_data for the callback. - - - - - - Sets the name of a source using its ID. - -This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. - -It is a programmer error to attempt to set the name of a non-existent -source. - -More specifically: source IDs can be reissued after a source has been -destroyed and therefore it is never valid to use this function with a -source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the -idle may already have run and been removed by the time this function -is called on its (now invalid) source ID. This source ID may have -been reissued, leading to the operation being performed against the -wrong source. - - - - - - - a #GSource ID - - - - debug name for the source - - - - - - Gets the smallest prime number from a built-in array of primes which -is larger than @num. This is used within GLib to calculate the optimum -size of a #GHashTable. - -The built-in array of primes ranges from 11 to 13845163 such that -each prime is approximately 1.5-2 times the previous prime. - - - the smallest prime number from a built-in array of primes - which is larger than @num - - - - - a #guint - - - - - - See g_spawn_async_with_pipes() for a full description; this function -simply calls the g_spawn_async_with_pipes() without any pipes. - -You should call g_spawn_close_pid() on the returned child process -reference when you don't need it any more. - -If you are writing a GTK+ application, and the program you are spawning is a -graphical application too, then to ensure that the spawned program opens its -windows on the right screen, you may want to use #GdkAppLaunchContext, -#GAppLaunchContext, or set the %DISPLAY environment variable. - -Note that the returned @child_pid on Windows is a handle to the child -process and not its identifier. Process handles and process identifiers -are different concepts on Windows. - - - %TRUE on success, %FALSE if error is set - - - - - child's current working - directory, or %NULL to inherit parent's - - - - - child's argument vector - - - - - - - child's environment, or %NULL to inherit parent's - - - - - - flags from #GSpawnFlags - - - - function to run in the child just before exec() - - - - user data for @child_setup - - - - return location for child process reference, or %NULL - - - - - - Identical to g_spawn_async_with_pipes() but instead of -creating pipes for the stdin/stdout/stderr, you can pass existing -file descriptors into this function through the @stdin_fd, -@stdout_fd and @stderr_fd parameters. The following @flags -also have their behaviour slightly tweaked as a result: - -%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output -will be discarded, instead of going to the same location as the parent's -standard output. If you use this flag, @standard_output must be -1. -%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error -will be discarded, instead of going to the same location as the parent's -standard error. If you use this flag, @standard_error must be -1. -%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's -standard input (by default, the child's standard input is attached to -/dev/null). If you use this flag, @standard_input must be -1. - -It is valid to pass the same fd in multiple parameters (e.g. you can pass -a single fd for both stdout and stderr). - - - %TRUE on success, %FALSE if an error was set - - - - - child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding - - - - child's argument vector, in the GLib file name encoding - - - - - - child's environment, or %NULL to inherit parent's, in the GLib file name encoding - - - - - - flags from #GSpawnFlags - - - - function to run in the child just before exec() - - - - user data for @child_setup - - - - return location for child process ID, or %NULL - - - - file descriptor to use for child's stdin, or -1 - - - - file descriptor to use for child's stdout, or -1 - - - - file descriptor to use for child's stderr, or -1 - - - - - - Executes a child program asynchronously (your program will not -block waiting for the child to exit). The child program is -specified by the only argument that must be provided, @argv. -@argv should be a %NULL-terminated array of strings, to be passed -as the argument vector for the child. The first string in @argv -is of course the name of the program to execute. By default, the -name of the program must be a full path. If @flags contains the -%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is -used to search for the executable. If @flags contains the -%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from -@envp is used to search for the executable. If both the -%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags -are set, the `PATH` variable from @envp takes precedence over -the environment variable. - -If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not -used, then the program will be run from the current directory (or -@working_directory, if specified); this might be unexpected or even -dangerous in some cases when the current directory is world-writable. - -On Windows, note that all the string or string vector arguments to -this function and the other g_spawn*() functions are in UTF-8, the -GLib file name encoding. Unicode characters that are not part of -the system codepage passed in these arguments will be correctly -available in the spawned program only if it uses wide character API -to retrieve its command line. For C programs built with Microsoft's -tools it is enough to make the program have a wmain() instead of -main(). wmain() has a wide character argument vector as parameter. - -At least currently, mingw doesn't support wmain(), so if you use -mingw to develop the spawned program, it should call -g_win32_get_command_line() to get arguments in UTF-8. - -On Windows the low-level child process creation API CreateProcess() -doesn't use argument vectors, but a command line. The C runtime -library's spawn*() family of functions (which g_spawn_async_with_pipes() -eventually calls) paste the argument vector elements together into -a command line, and the C runtime startup code does a corresponding -reconstruction of an argument vector from the command line, to be -passed to main(). Complications arise when you have argument vector -elements that contain spaces or double quotes. The `spawn*()` functions -don't do any quoting or escaping, but on the other hand the startup -code does do unquoting and unescaping in order to enable receiving -arguments with embedded spaces or double quotes. To work around this -asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on -argument vector elements that need it before calling the C runtime -spawn() function. - -The returned @child_pid on Windows is a handle to the child -process, not its identifier. Process handles and process -identifiers are different concepts on Windows. - -@envp is a %NULL-terminated array of strings, where each string -has the form `KEY=VALUE`. This will become the child's environment. -If @envp is %NULL, the child inherits its parent's environment. - -@flags should be the bitwise OR of any flags you want to affect the -function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the -child will not automatically be reaped; you must use a child watch -(g_child_watch_add()) to be notified about the death of the child process, -otherwise it will stay around as a zombie process until this process exits. -Eventually you must call g_spawn_close_pid() on the @child_pid, in order to -free resources which may be associated with the child process. (On Unix, -using a child watch is equivalent to calling waitpid() or handling -the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() -is equivalent to calling CloseHandle() on the process handle returned -in @child_pid). See g_child_watch_add(). - -Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically -closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that -other open file descriptors will be inherited by the child; otherwise all -descriptors except stdin/stdout/stderr will be closed before calling exec() -in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an -absolute path, it will be looked for in the `PATH` environment -variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an -absolute path, it will be looked for in the `PATH` variable from -@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP -are used, the value from @envp takes precedence over the environment. -%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output -will be discarded, instead of going to the same location as the parent's -standard output. If you use this flag, @standard_output must be %NULL. -%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error -will be discarded, instead of going to the same location as the parent's -standard error. If you use this flag, @standard_error must be %NULL. -%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's -standard input (by default, the child's standard input is attached to -`/dev/null`). If you use this flag, @standard_input must be %NULL. -%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is -the file to execute, while the remaining elements are the actual -argument vector to pass to the file. Normally g_spawn_async_with_pipes() -uses @argv[0] as the file to execute, and passes all of @argv to the child. - -@child_setup and @user_data are a function and user data. On POSIX -platforms, the function is called in the child after GLib has -performed all the setup it plans to perform (including creating -pipes, closing file descriptors, etc.) but before calling exec(). -That is, @child_setup is called just before calling exec() in the -child. Obviously actions taken in this function will only affect -the child, not the parent. - -On Windows, there is no separate fork() and exec() functionality. -Child processes are created and run with a single API call, -CreateProcess(). There is no sensible thing @child_setup -could be used for on Windows so it is ignored and not called. - -If non-%NULL, @child_pid will on Unix be filled with the child's -process ID. You can use the process ID to send signals to the child, -or to use g_child_watch_add() (or waitpid()) if you specified the -%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be -filled with a handle to the child process only if you specified the -%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child -process using the Win32 API, for example wait for its termination -with the WaitFor*() functions, or examine its exit code with -GetExitCodeProcess(). You should close the handle with CloseHandle() -or g_spawn_close_pid() when you no longer need it. - -If non-%NULL, the @standard_input, @standard_output, @standard_error -locations will be filled with file descriptors for writing to the child's -standard input or reading from its standard output or standard error. -The caller of g_spawn_async_with_pipes() must close these file descriptors -when they are no longer in use. If these parameters are %NULL, the -corresponding pipe won't be created. - -If @standard_input is %NULL, the child's standard input is attached to -`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. - -If @standard_error is NULL, the child's standard error goes to the same -location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL -is set. - -If @standard_output is NULL, the child's standard output goes to the same -location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL -is set. - -@error can be %NULL to ignore errors, or non-%NULL to report errors. -If an error is set, the function returns %FALSE. Errors are reported -even if they occur in the child (for example if the executable in -@argv[0] is not found). Typically the `message` field of returned -errors should be displayed to users. Possible errors are those from -the #G_SPAWN_ERROR domain. - -If an error occurs, @child_pid, @standard_input, @standard_output, -and @standard_error will not be filled with valid values. - -If @child_pid is not %NULL and an error does not occur then the returned -process reference must be closed using g_spawn_close_pid(). - -On modern UNIX platforms, GLib can use an efficient process launching -codepath driven internally by posix_spawn(). This has the advantage of -avoiding the fork-time performance costs of cloning the parent process -address space, and avoiding associated memory overcommit checks that are -not relevant in the context of immediately executing a distinct process. -This optimized codepath will be used provided that the following conditions -are met: - -1. %G_SPAWN_DO_NOT_REAP_CHILD is set -2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set -3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set -4. @working_directory is %NULL -5. @child_setup is %NULL -6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. - -If you are writing a GTK+ application, and the program you are spawning is a -graphical application too, then to ensure that the spawned program opens its -windows on the right screen, you may want to use #GdkAppLaunchContext, -#GAppLaunchContext, or set the %DISPLAY environment variable. - - - %TRUE on success, %FALSE if an error was set - - - - - child's current working - directory, or %NULL to inherit parent's, in the GLib file name encoding - - - - child's argument - vector, in the GLib file name encoding - - - - - - - child's environment, or %NULL to inherit parent's, in the GLib file - name encoding - - - - - - flags from #GSpawnFlags - - - - function to run in the child just before exec() - - - - user data for @child_setup - - - - return location for child process ID, or %NULL - - - - return location for file descriptor to write to child's stdin, or %NULL - - - - return location for file descriptor to read child's stdout, or %NULL - - - - return location for file descriptor to read child's stderr, or %NULL - - - - - - Set @error if @exit_status indicates the child exited abnormally -(e.g. with a nonzero exit code, or via a fatal signal). - -The g_spawn_sync() and g_child_watch_add() family of APIs return an -exit status for subprocesses encoded in a platform-specific way. -On Unix, this is guaranteed to be in the same format waitpid() returns, -and on Windows it is guaranteed to be the result of GetExitCodeProcess(). - -Prior to the introduction of this function in GLib 2.34, interpreting -@exit_status required use of platform-specific APIs, which is problematic -for software using GLib as a cross-platform layer. - -Additionally, many programs simply want to determine whether or not -the child exited successfully, and either propagate a #GError or -print a message to standard error. In that common case, this function -can be used. Note that the error message in @error will contain -human-readable information about the exit status. - -The @domain and @code of @error have special semantics in the case -where the process has an "exit code", as opposed to being killed by -a signal. On Unix, this happens if WIFEXITED() would be true of -@exit_status. On Windows, it is always the case. - -The special semantics are that the actual exit code will be the -code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. -This allows you to differentiate between different exit codes. - -If the process was terminated by some means other than an exit -status, the domain will be %G_SPAWN_ERROR, and the code will be -%G_SPAWN_ERROR_FAILED. - -This function just offers convenience; you can of course also check -the available platform via a macro such as %G_OS_UNIX, and use -WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt -to scan or parse the error message string; it may be translated and/or -change in future versions of GLib. - - - %TRUE if child exited successfully, %FALSE otherwise (and - @error will be set) - - - - - An exit code as returned from g_spawn_sync() - - - - - - On some platforms, notably Windows, the #GPid type represents a resource -which must be closed to prevent resource leaking. g_spawn_close_pid() -is provided for this purpose. It should be used on all platforms, even -though it doesn't do anything under UNIX. - - - - - - - The process reference to close - - - - - - A simple version of g_spawn_async() that parses a command line with -g_shell_parse_argv() and passes it to g_spawn_async(). Runs a -command line in the background. Unlike g_spawn_async(), the -%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note -that %G_SPAWN_SEARCH_PATH can have security implications, so -consider using g_spawn_async() directly if appropriate. Possible -errors are those from g_shell_parse_argv() and g_spawn_async(). - -The same concerns on Windows apply as for g_spawn_command_line_sync(). - - - %TRUE on success, %FALSE if error is set - - - - - a command line - - - - - - A simple version of g_spawn_sync() with little-used parameters -removed, taking a command line instead of an argument vector. See -g_spawn_sync() for full details. @command_line will be parsed by -g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag -is enabled. Note that %G_SPAWN_SEARCH_PATH can have security -implications, so consider using g_spawn_sync() directly if -appropriate. Possible errors are those from g_spawn_sync() and those -from g_shell_parse_argv(). - -If @exit_status is non-%NULL, the platform-specific exit status of -the child is stored there; see the documentation of -g_spawn_check_exit_status() for how to use and interpret this. - -On Windows, please note the implications of g_shell_parse_argv() -parsing @command_line. Parsing is done according to Unix shell rules, not -Windows command interpreter rules. -Space is a separator, and backslashes are -special. Thus you cannot simply pass a @command_line containing -canonical Windows paths, like "c:\\program files\\app\\app.exe", as -the backslashes will be eaten, and the space will act as a -separator. You need to enclose such paths with single quotes, like -"'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". - - - %TRUE on success, %FALSE if an error was set - - - - - a command line - - - - return location for child output - - - - - - return location for child errors - - - - - - return location for child exit status, as returned by waitpid() - - - - - - - - - - - - - - - - Executes a child synchronously (waits for the child to exit before returning). -All output from the child is stored in @standard_output and @standard_error, -if those parameters are non-%NULL. Note that you must set the -%G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when -passing %NULL for @standard_output and @standard_error. - -If @exit_status is non-%NULL, the platform-specific exit status of -the child is stored there; see the documentation of -g_spawn_check_exit_status() for how to use and interpret this. -Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in -@flags, and on POSIX platforms, the same restrictions as for -g_child_watch_source_new() apply. - -If an error occurs, no data is returned in @standard_output, -@standard_error, or @exit_status. - -This function calls g_spawn_async_with_pipes() internally; see that -function for full details on the other parameters and details on -how these functions work on Windows. - - - %TRUE on success, %FALSE if an error was set - - - - - child's current working - directory, or %NULL to inherit parent's - - - - - child's argument vector - - - - - - - child's environment, or %NULL to inherit parent's - - - - - - flags from #GSpawnFlags - - - - function to run in the child just before exec() - - - - user data for @child_setup - - - - return location for child output, or %NULL - - - - - - return location for child error messages, or %NULL - - - - - - return location for child exit status, as returned by waitpid(), or %NULL - - - - - - An implementation of the standard sprintf() function which supports -positional parameters, as specified in the Single Unix Specification. - -Note that it is usually better to use g_snprintf(), to avoid the -risk of buffer overflow. - -`glib/gprintf.h` must be explicitly included in order to use this function. - -See also g_strdup_printf(). - - - the number of bytes printed. - - - - - A pointer to a memory buffer to contain the resulting string. It - is up to the caller to ensure that the allocated buffer is large - enough to hold the formatted result - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the arguments to insert in the output. - - - - - - Sets @pp to %NULL, returning the value that was there before. - -Conceptually, this transfers the ownership of the pointer from the -referenced variable to the "caller" of the macro (ie: "steals" the -reference). - -The return value will be properly typed, according to the type of -@pp. - -This can be very useful when combined with g_autoptr() to prevent the -return value of a function from being automatically freed. Consider -the following example (which only works on GCC and clang): - -|[ -GObject * -create_object (void) -{ - g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL); - - if (early_error_case) - return NULL; - - return g_steal_pointer (&obj); -} -]| - -It can also be used in similar ways for 'out' parameters and is -particularly useful for dealing with optional out parameters: - -|[ -gboolean -get_object (GObject **obj_out) -{ - g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL); - - if (early_error_case) - return FALSE; - - if (obj_out) - *obj_out = g_steal_pointer (&obj); - - return TRUE; -} -]| - -In the above example, the object will be automatically freed in the -early error case and also in the case that %NULL was given for -@obj_out. - - - - a pointer to a pointer - - - - - Copies a nul-terminated string into the dest buffer, include the -trailing nul, and return a pointer to the trailing nul byte. -This is useful for concatenating multiple strings together -without having to repeatedly scan for the end. - - - a pointer to trailing nul byte. - - - - - destination buffer. - - - - source string. - - - - - - Compares two strings for byte-by-byte equality and returns %TRUE -if they are equal. It can be passed to g_hash_table_new() as the -@key_equal_func parameter, when using non-%NULL strings as keys in a -#GHashTable. - -This function is typically used for hash table comparisons, but can be used -for general purpose comparisons of non-%NULL strings. For a %NULL-safe string -comparison function, see g_strcmp0(). - - - %TRUE if the two keys match - - - - - a key - - - - a key to compare with @v1 - - - - - - Looks whether the string @str begins with @prefix. - - - %TRUE if @str begins with @prefix, %FALSE otherwise. - - - - - a nul-terminated string - - - - the nul-terminated prefix to look for - - - - - - Looks whether the string @str ends with @suffix. - - - %TRUE if @str end with @suffix, %FALSE otherwise. - - - - - a nul-terminated string - - - - the nul-terminated suffix to look for - - - - - - Converts a string to a hash value. - -This function implements the widely used "djb" hash apparently -posted by Daniel Bernstein to comp.lang.c some time ago. The 32 -bit unsigned hash value starts at 5381 and for each byte 'c' in -the string, is updated: `hash = hash * 33 + c`. This function -uses the signed value of each byte. - -It can be passed to g_hash_table_new() as the @hash_func parameter, -when using non-%NULL strings as keys in a #GHashTable. - -Note that this function may not be a perfect fit for all use cases. -For example, it produces some hash collisions with strings as short -as 2. - - - a hash value corresponding to the key - - - - - a string key - - - - - - Determines if a string is pure ASCII. A string is pure ASCII if it -contains no bytes with the high bit set. - - - %TRUE if @str is ASCII - - - - - a string - - - - - - Checks if a search conducted for @search_term should match -@potential_hit. - -This function calls g_str_tokenize_and_fold() on both -@search_term and @potential_hit. ASCII alternates are never taken -for @search_term but will be taken for @potential_hit according to -the value of @accept_alternates. - -A hit occurs when each folded token in @search_term is a prefix of a -folded token from @potential_hit. - -Depending on how you're performing the search, it will typically be -faster to call g_str_tokenize_and_fold() on each string in -your corpus and build an index on the returned folded tokens, then -call g_str_tokenize_and_fold() on the search term and -perform lookups into that index. - -As some examples, searching for ‘fred’ would match the potential hit -‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match -‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of -accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo -Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). - - - %TRUE if @potential_hit is a hit - - - - - the search term from the user - - - - the text that may be a hit - - - - %TRUE to accept ASCII alternates - - - - - - Transliterate @str to plain ASCII. - -For best results, @str should be in composed normalised form. - -This function performs a reasonably good set of character -replacements. The particular set of replacements that is done may -change by version or even by runtime environment. - -If the source language of @str is known, it can used to improve the -accuracy of the translation by passing it as @from_locale. It should -be a valid POSIX locale string (of the form -`language[_territory][.codeset][@modifier]`). - -If @from_locale is %NULL then the current locale is used. - -If you want to do translation for no specific locale, and you want it -to be done independently of the currently locale, specify `"C"` for -@from_locale. - - - a string in plain ASCII - - - - - a string, in UTF-8 - - - - the source locale, if known - - - - - - Tokenises @string and performs folding on each token. - -A token is a non-empty sequence of alphanumeric characters in the -source string, separated by non-alphanumeric characters. An -"alphanumeric" character for this purpose is one that matches -g_unichar_isalnum() or g_unichar_ismark(). - -Each token is then (Unicode) normalised and case-folded. If -@ascii_alternates is non-%NULL and some of the returned tokens -contain non-ASCII characters, ASCII alternatives will be generated. - -The number of ASCII alternatives that are generated and the method -for doing so is unspecified, but @translit_locale (if specified) may -improve the transliteration if the language of the source string is -known. - - - the folded tokens - - - - - - - a string - - - - the language code (like 'de' or - 'en_GB') from which @string originates - - - - a - return location for ASCII alternates - - - - - - - - For each character in @string, if the character is not in @valid_chars, -replaces the character with @substitutor. Modifies @string in place, -and return @string itself, not a copy. The return value is to allow -nesting such as -|[<!-- language="C" --> - g_ascii_strup (g_strcanon (str, "abc", '?')) -]| - -In order to modify a copy, you may use `g_strdup()`: -|[<!-- language="C" --> - reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); - ... - g_free (reformatted); -]| - - - @string - - - - - a nul-terminated array of bytes - - - - bytes permitted in @string - - - - replacement character for disallowed bytes - - - - - - A case-insensitive string comparison, corresponding to the standard -strcasecmp() function on platforms which support it. - See g_strncasecmp() for a discussion of why this - function is deprecated and how to replace it. - - - 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. - - - - - a string - - - - a string to compare with @s1 - - - - - - Removes trailing whitespace from a string. - -This function doesn't allocate or reallocate any memory; -it modifies @string in place. Therefore, it cannot be used -on statically allocated strings. - -The pointer to @string is returned to allow the nesting of functions. - -Also see g_strchug() and g_strstrip(). - - - @string - - - - - a string to remove the trailing whitespace from - - - - - - Removes leading whitespace from a string, by moving the rest -of the characters forward. - -This function doesn't allocate or reallocate any memory; -it modifies @string in place. Therefore, it cannot be used on -statically allocated strings. - -The pointer to @string is returned to allow the nesting of functions. - -Also see g_strchomp() and g_strstrip(). - - - @string - - - - - a string to remove the leading whitespace from - - - - - - Compares @str1 and @str2 like strcmp(). Handles %NULL -gracefully by sorting it before non-%NULL strings. -Comparing two %NULL pointers returns 0. - - - an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. - - - - - a C string or %NULL - - - - another C string or %NULL - - - - - - Replaces all escaped characters with their one byte equivalent. - -This function does the reverse conversion of g_strescape(). - - - a newly-allocated copy of @source with all escaped - character compressed - - - - - a string to compress - - - - - - Concatenates all of the given strings into one long string. The -returned string should be freed with g_free() when no longer needed. - -The variable argument list must end with %NULL. If you forget the %NULL, -g_strconcat() will start appending random memory junk to your string. - -Note that this function is usually not the right function to use to -assemble a translated message from pieces, since proper translation -often requires the pieces to be reordered. - - - a newly-allocated string containing all the string arguments - - - - - the first string to add, which must not be %NULL - - - - a %NULL-terminated list of strings to append to the string - - - - - - Converts any delimiter characters in @string to @new_delimiter. -Any characters in @string which are found in @delimiters are -changed to the @new_delimiter character. Modifies @string in place, -and returns @string itself, not a copy. The return value is to -allow nesting such as -|[<!-- language="C" --> - g_ascii_strup (g_strdelimit (str, "abc", '?')) -]| - -In order to modify a copy, you may use `g_strdup()`: -|[<!-- language="C" --> - reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); - ... - g_free (reformatted); -]| - - - @string - - - - - the string to convert - - - - a string containing the current delimiters, - or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS - - - - the new delimiter character - - - - - - Converts a string to lower case. - This function is totally broken for the reasons discussed -in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() -instead. - - - the string - - - - - the string to convert. - - - - - - Duplicates a string. If @str is %NULL it returns %NULL. -The returned string should be freed with g_free() -when no longer needed. - - - a newly-allocated copy of @str - - - - - the string to duplicate - - - - - - Similar to the standard C sprintf() function but safer, since it -calculates the maximum space required and allocates memory to hold -the result. The returned string should be freed with g_free() when no -longer needed. - -The returned string is guaranteed to be non-NULL, unless @format -contains `%lc` or `%ls` conversions, which can fail if no multibyte -representation is available for the given character. - - - a newly-allocated string holding the result - - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the parameters to insert into the format string - - - - - - Similar to the standard C vsprintf() function but safer, since it -calculates the maximum space required and allocates memory to hold -the result. The returned string should be freed with g_free() when -no longer needed. - -The returned string is guaranteed to be non-NULL, unless @format -contains `%lc` or `%ls` conversions, which can fail if no multibyte -representation is available for the given character. - -See also g_vasprintf(), which offers the same functionality, but -additionally returns the length of the allocated string. - - - a newly-allocated string holding the result - - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the list of parameters to insert into the format string - - - - - - Copies %NULL-terminated array of strings. The copy is a deep copy; -the new array should be freed by first freeing each string, then -the array itself. g_strfreev() does this for you. If called -on a %NULL value, g_strdupv() simply returns %NULL. - - - a new %NULL-terminated array of strings. - - - - - - - a %NULL-terminated array of strings - - - - - - Returns a string corresponding to the given error code, e.g. "no -such process". Unlike strerror(), this always returns a string in -UTF-8 encoding, and the pointer is guaranteed to remain valid for -the lifetime of the process. - -Note that the string may be translated according to the current locale. - -The value of %errno will not be changed by this function. However, it may -be changed by intermediate function calls, so you should save its value -as soon as the call returns: -|[ - int saved_errno; - - ret = read (blah); - saved_errno = errno; - - g_strerror (saved_errno); -]| - - - a UTF-8 string describing the error code. If the error code - is unknown, it returns a string like "unknown error (<code>)". - - - - - the system error number. See the standard C %errno - documentation - - - - - - Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' -and '"' in the string @source by inserting a '\' before -them. Additionally all characters in the range 0x01-0x1F (everything -below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are -replaced with a '\' followed by their octal representation. -Characters supplied in @exceptions are not escaped. - -g_strcompress() does the reverse conversion. - - - a newly-allocated copy of @source with certain - characters escaped. See above. - - - - - a string to escape - - - - a string of characters not to escape in @source - - - - - - Frees a %NULL-terminated array of strings, as well as each -string it contains. - -If @str_array is %NULL, this function simply returns. - - - - - - - a %NULL-terminated array of strings to free - - - - - - Creates a new #GString, initialized with the given string. - - - the new #GString - - - - - the initial text to copy into the string, or %NULL to -start with an empty string - - - - - - Creates a new #GString with @len bytes of the @init buffer. -Because a length is provided, @init need not be nul-terminated, -and can contain embedded nul bytes. - -Since this function does not stop at nul bytes, it is the caller's -responsibility to ensure that @init has at least @len addressable -bytes. - - - a new #GString - - - - - initial contents of the string - - - - length of @init to use - - - - - - Creates a new #GString, with enough space for @dfl_size -bytes. This is useful if you are going to add a lot of -text to the string and don't want it to be reallocated -too often. - - - the new #GString - - - - - the default size of the space allocated to - hold the string - - - - - - An auxiliary function for gettext() support (see Q_()). - - - @msgval, unless @msgval is identical to @msgid - and contains a '|' character, in which case a pointer to - the substring of msgid after the first '|' character is returned. - - - - - a string - - - - another string - - - - - - Joins a number of strings together to form one long string, with the -optional @separator inserted between each of them. The returned string -should be freed with g_free(). - - - a newly-allocated string containing all of the strings joined - together, with @separator between them - - - - - a string to insert between each of the - strings, or %NULL - - - - a %NULL-terminated list of strings to join - - - - - - Joins a number of strings together to form one long string, with the -optional @separator inserted between each of them. The returned string -should be freed with g_free(). - -If @str_array has no items, the return value will be an -empty string. If @str_array contains a single item, @separator will not -appear in the resulting string. - - - a newly-allocated string containing all of the strings joined - together, with @separator between them - - - - - a string to insert between each of the - strings, or %NULL - - - - a %NULL-terminated array of strings to join - - - - - - Portability wrapper that calls strlcat() on systems which have it, -and emulates it otherwise. Appends nul-terminated @src string to @dest, -guaranteeing nul-termination for @dest. The total size of @dest won't -exceed @dest_size. - -At most @dest_size - 1 characters will be copied. Unlike strncat(), -@dest_size is the full size of dest, not the space left over. This -function does not allocate memory. It always nul-terminates (unless -@dest_size == 0 or there were no nul characters in the @dest_size -characters of dest to start with). - -Caveat: this is supposedly a more secure alternative to strcat() or -strncat(), but for real security g_strconcat() is harder to mess up. - - - size of attempted result, which is MIN (dest_size, strlen - (original dest)) + strlen (src), so if retval >= dest_size, - truncation occurred. - - - - - destination buffer, already containing one nul-terminated string - - - - source buffer - - - - length of @dest buffer in bytes (not length of existing string - inside @dest) - - - - - - Portability wrapper that calls strlcpy() on systems which have it, -and emulates strlcpy() otherwise. Copies @src to @dest; @dest is -guaranteed to be nul-terminated; @src must be nul-terminated; -@dest_size is the buffer size, not the number of bytes to copy. - -At most @dest_size - 1 characters will be copied. Always nul-terminates -(unless @dest_size is 0). This function does not allocate memory. Unlike -strncpy(), this function doesn't pad @dest (so it's often faster). It -returns the size of the attempted result, strlen (src), so if -@retval >= @dest_size, truncation occurred. - -Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), -but if you really want to avoid screwups, g_strdup() is an even better -idea. - - - length of @src - - - - - destination buffer - - - - source buffer - - - - length of @dest in bytes - - - - - - A case-insensitive string comparison, corresponding to the standard -strncasecmp() function on platforms which support it. It is similar -to g_strcasecmp() except it only compares the first @n characters of -the strings. - The problem with g_strncasecmp() is that it does - the comparison by calling toupper()/tolower(). These functions - are locale-specific and operate on single bytes. However, it is - impossible to handle things correctly from an internationalization - standpoint by operating on bytes, since characters may be multibyte. - Thus g_strncasecmp() is broken if your string is guaranteed to be - ASCII, since it is locale-sensitive, and it's broken if your string - is localized, since it doesn't work on many encodings at all, - including UTF-8, EUC-JP, etc. - - There are therefore two replacement techniques: g_ascii_strncasecmp(), - which only works on ASCII and is not locale-sensitive, and - g_utf8_casefold() followed by strcmp() on the resulting strings, - which is good for case-insensitive sorting of UTF-8. - - - 0 if the strings match, a negative value if @s1 < @s2, - or a positive value if @s1 > @s2. - - - - - a string - - - - a string to compare with @s1 - - - - the maximum number of characters to compare - - - - - - Duplicates the first @n bytes of a string, returning a newly-allocated -buffer @n + 1 bytes long which will always be nul-terminated. If @str -is less than @n bytes long the buffer is padded with nuls. If @str is -%NULL it returns %NULL. The returned value should be freed when no longer -needed. - -To copy a number of characters from a UTF-8 encoded string, -use g_utf8_strncpy() instead. - - - a newly-allocated buffer containing the first @n bytes - of @str, nul-terminated - - - - - the string to duplicate - - - - the maximum number of bytes to copy from @str - - - - - - Creates a new string @length bytes long filled with @fill_char. -The returned string should be freed when no longer needed. - - - a newly-allocated string filled the @fill_char - - - - - the length of the new string - - - - the byte to fill the string with - - - - - - Reverses all of the bytes in a string. For example, -`g_strreverse ("abcdef")` will result in "fedcba". - -Note that g_strreverse() doesn't work on UTF-8 strings -containing multibyte characters. For that purpose, use -g_utf8_strreverse(). - - - the same pointer passed in as @string - - - - - the string to reverse - - - - - - Searches the string @haystack for the last occurrence -of the string @needle. - - - a pointer to the found occurrence, or - %NULL if not found. - - - - - a nul-terminated string - - - - the nul-terminated string to search for - - - - - - Searches the string @haystack for the last occurrence -of the string @needle, limiting the length of the search -to @haystack_len. - - - a pointer to the found occurrence, or - %NULL if not found. - - - - - a nul-terminated string - - - - the maximum length of @haystack - - - - the nul-terminated string to search for - - - - - - Returns a string describing the given signal, e.g. "Segmentation fault". -You should use this function in preference to strsignal(), because it -returns a string in UTF-8 encoding, and since not all platforms support -the strsignal() function. - - - a UTF-8 string describing the signal. If the signal is unknown, - it returns "unknown signal (<signum>)". - - - - - the signal number. See the `signal` documentation - - - - - - Splits a string into a maximum of @max_tokens pieces, using the given -@delimiter. If @max_tokens is reached, the remainder of @string is -appended to the last token. - -As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a -%NULL-terminated vector containing the six strings "", "a", "bc", "", "d" -and "". - -As a special case, the result of splitting the empty string "" is an empty -vector, not a vector containing a single string. The reason for this -special case is that being able to represent an empty vector is typically -more useful than consistent handling of empty elements. If you do need -to represent empty elements, you'll need to check for the empty string -before calling g_strsplit(). - - - a newly-allocated %NULL-terminated array of strings. Use - g_strfreev() to free it. - - - - - - - a string to split - - - - a string which specifies the places at which to split - the string. The delimiter is not included in any of the resulting - strings, unless @max_tokens is reached. - - - - the maximum number of pieces to split @string into. - If this is less than 1, the string is split completely. - - - - - - Splits @string into a number of tokens not containing any of the characters -in @delimiter. A token is the (possibly empty) longest string that does not -contain any of the characters in @delimiters. If @max_tokens is reached, the -remainder is appended to the last token. - -For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a -%NULL-terminated vector containing the three strings "abc", "def", -and "ghi". - -The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated -vector containing the four strings "", "def", "ghi", and "". - -As a special case, the result of splitting the empty string "" is an empty -vector, not a vector containing a single string. The reason for this -special case is that being able to represent an empty vector is typically -more useful than consistent handling of empty elements. If you do need -to represent empty elements, you'll need to check for the empty string -before calling g_strsplit_set(). - -Note that this function works on bytes not characters, so it can't be used -to delimit UTF-8 strings for anything but ASCII characters. - - - a newly-allocated %NULL-terminated array of strings. Use - g_strfreev() to free it. - - - - - - - The string to be tokenized - - - - A nul-terminated string containing bytes that are used - to split the string. - - - - The maximum number of tokens to split @string into. - If this is less than 1, the string is split completely - - - - - - Searches the string @haystack for the first occurrence -of the string @needle, limiting the length of the search -to @haystack_len. - - - a pointer to the found occurrence, or - %NULL if not found. - - - - - a string - - - - the maximum length of @haystack. Note that -1 is - a valid length, if @haystack is nul-terminated, meaning it will - search through the whole string. - - - - the string to search for - - - - - - Removes leading and trailing whitespace from a string. -See g_strchomp() and g_strchug(). - - - - a string to remove the leading and trailing whitespace from - - - - - Converts a string to a #gdouble value. -It calls the standard strtod() function to handle the conversion, but -if the string is not completely converted it attempts the conversion -again with g_ascii_strtod(), and returns the best match. - -This function should seldom be used. The normal situation when reading -numbers not for human consumption is to use g_ascii_strtod(). Only when -you know that you must expect both locale formatted and C formatted numbers -should you use this. Make sure that you don't pass strings such as comma -separated lists of values, since the commas may be interpreted as a decimal -point in some locales, causing unexpected results. - - - the #gdouble value. - - - - - the string to convert to a numeric value. - - - - if non-%NULL, it returns the - character after the last character used in the conversion. - - - - - - Converts a string to upper case. - This function is totally broken for the reasons - discussed in the g_strncasecmp() docs - use g_ascii_strup() - or g_utf8_strup() instead. - - - the string - - - - - the string to convert - - - - - - Checks if @strv contains @str. @strv must not be %NULL. - - - %TRUE if @str is an element of @strv, according to g_str_equal(). - - - - - a %NULL-terminated array of strings - - - - a string - - - - - - Checks if @strv1 and @strv2 contain exactly the same elements in exactly the -same order. Elements are compared using g_str_equal(). To match independently -of order, sort the arrays first (using g_qsort_with_data() or similar). - -Two empty arrays are considered equal. Neither @strv1 not @strv2 may be -%NULL. - - - %TRUE if @strv1 and @strv2 are equal - - - - - a %NULL-terminated array of strings - - - - another %NULL-terminated array of strings - - - - - - - - - - - - Returns the length of the given %NULL-terminated -string array @str_array. @str_array must not be %NULL. - - - length of @str_array. - - - - - a %NULL-terminated array of strings - - - - - - Hook up a new test case at @testpath, similar to g_test_add_func(). -A fixture data structure with setup and teardown functions may be provided, -similar to g_test_create_case(). - -g_test_add() is implemented as a macro, so that the fsetup(), ftest() and -fteardown() callbacks can expect a @Fixture pointer as their first argument -in a type safe manner. They otherwise have type #GTestFixtureFunc. - - - - The test path for a new test case. - - - The type of a fixture data structure. - - - Data argument for the test functions. - - - The function to set up the fixture data. - - - The actual test function. - - - The function to tear down the fixture data. - - - - - Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. The @test_data argument -will be passed as first argument to @test_func. - -If @testpath includes the component "subprocess" anywhere in it, -the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). - -No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. - - - - - - - /-separated test case path name for the test. - - - - Test data argument for the test function. - - - - The test function to invoke for this test. - - - - - - Create a new test case, as with g_test_add_data_func(), but freeing -@test_data after the test run is complete. - - - - - - - /-separated test case path name for the test. - - - - Test data argument for the test function. - - - - The test function to invoke for this test. - - - - #GDestroyNotify for @test_data. - - - - - - Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. - -If @testpath includes the component "subprocess" anywhere in it, -the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). - -No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. - - - - - - - /-separated test case path name for the test. - - - - The test function to invoke for this test. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function adds a message to test reports that -associates a bug URI with a test case. -Bug URIs are constructed from a base URI set with g_test_bug_base() -and @bug_uri_snippet. If g_test_bug_base() has not been called, it is -assumed to be the empty string, so a full URI can be provided to -g_test_bug() instead. - -See also: g_test_summary() - - - - - - - Bug specific bug tracker URI portion. - - - - - - Specify the base URI for bug reports. - -The base URI is used to construct bug report messages for -g_test_message() when g_test_bug() is called. -Calling this function outside of a test case sets the -default base URI for all test cases. Calling it from within -a test case changes the base URI for the scope of the test -case only. -Bug URIs are constructed by appending a bug specific URI -portion to @uri_pattern, or by replacing the special string -'\%s' within @uri_pattern if that is present. - -If g_test_bug_base() is not called, bug URIs are formed solely -from the value provided by g_test_bug(). - - - - - - - the base pattern for bug URIs - - - - - - Creates the pathname to a data file that is required for a test. - -This function is conceptually similar to g_build_filename() except -that the first argument has been replaced with a #GTestFileType -argument. - -The data file should either have been distributed with the module -containing the test (%G_TEST_DIST) or built as part of the build -system of that module (%G_TEST_BUILT). - -In order for this function to work in srcdir != builddir situations, -the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to -have been defined. As of 2.38, this is done by the glib.mk -included in GLib. Please ensure that your copy is up to date before -using this function. - -In case neither variable is set, this function will fall back to -using the dirname portion of argv[0], possibly removing ".libs". -This allows for casual running of tests directly from the commandline -in the srcdir == builddir case and should also support running of -installed tests, assuming the data files have been installed in the -same relative path as the test binary. - - - the path of the file, to be freed using g_free() - - - - - the type of file (built vs. distributed) - - - - the first segment of the pathname - - - - %NULL-terminated additional path segments - - - - - - Create a new #GTestCase, named @test_name, this API is fairly -low level, calling g_test_add() or g_test_add_func() is preferable. -When this test is executed, a fixture structure of size @data_size -will be automatically allocated and filled with zeros. Then @data_setup is -called to initialize the fixture. After fixture setup, the actual test -function @data_test is called. Once the test run completes, the -fixture structure is torn down by calling @data_teardown and -after that the memory is automatically released by the test framework. - -Splitting up a test run into fixture setup, test function and -fixture teardown is most useful if the same fixture is used for -multiple tests. In this cases, g_test_create_case() will be -called with the same fixture, but varying @test_name and -@data_test arguments. - - - a newly allocated #GTestCase. - - - - - the name for the test case - - - - the size of the fixture data structure - - - - test data argument for the test functions - - - - the function to set up the fixture data - - - - the actual test function - - - - the function to teardown the fixture data - - - - - - Create a new test suite with the name @suite_name. - - - A newly allocated #GTestSuite instance. - - - - - a name for the suite - - - - - - Indicates that a message with the given @log_domain and @log_level, -with text matching @pattern, is expected to be logged. When this -message is logged, it will not be printed, and the test case will -not abort. - -This API may only be used with the old logging API (g_log() without -%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging -API. See [Testing for Messages][testing-for-messages]. - -Use g_test_assert_expected_messages() to assert that all -previously-expected messages have been seen and suppressed. - -You can call this multiple times in a row, if multiple messages are -expected as a result of a single call. (The messages must appear in -the same order as the calls to g_test_expect_message().) - -For example: - -|[<!-- language="C" --> - // g_main_context_push_thread_default() should fail if the - // context is already owned by another thread. - g_test_expect_message (G_LOG_DOMAIN, - G_LOG_LEVEL_CRITICAL, - "assertion*acquired_context*failed"); - g_main_context_push_thread_default (bad_context); - g_test_assert_expected_messages (); -]| - -Note that you cannot use this to test g_error() messages, since -g_error() intentionally never returns even if the program doesn't -abort; use g_test_trap_subprocess() in this case. - -If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly -expected via g_test_expect_message() then they will be ignored. - - - - - - - the log domain of the message - - - - the log level of the message - - - - a glob-style [pattern][glib-Glob-style-pattern-matching] - - - - - - Indicates that a test failed. This function can be called -multiple times from the same test. You can use this function -if your test failed in a recoverable way. - -Do not use this function if the failure of a test could cause -other tests to malfunction. - -Calling this function will not stop the test from running, you -need to return from the test function yourself. So you can -produce additional diagnostic messages or even continue running -the test. - -If not called from inside a test, this function does nothing. - - - - - - - Returns whether a test has already failed. This will -be the case when g_test_fail(), g_test_incomplete() -or g_test_skip() have been called, but also if an -assertion has failed. - -This can be useful to return early from a test if -continuing after a failed assertion might be harmful. - -The return value of this function is only meaningful -if it is called from inside a test function. - - - %TRUE if the test has failed - - - - - Gets the pathname of the directory containing test files of the type -specified by @file_type. - -This is approximately the same as calling g_test_build_filename("."), -but you don't need to free the return value. - - - the path of the directory, owned by GLib - - - - - the type of file (built vs. distributed) - - - - - - Gets the pathname to a data file that is required for a test. - -This is the same as g_test_build_filename() with two differences. -The first difference is that must only use this function from within -a testcase function. The second difference is that you need not free -the return value -- it will be automatically freed when the testcase -finishes running. - -It is safe to use this function from a thread inside of a testcase -but you must ensure that all such uses occur before the main testcase -function returns (ie: it is best to ensure that all threads have been -joined). - - - the path, automatically freed at the end of the testcase - - - - - the type of file (built vs. distributed) - - - - the first segment of the pathname - - - - %NULL-terminated additional path segments - - - - - - Get the toplevel test suite for the test path API. - - - the toplevel #GTestSuite - - - - - Indicates that a test failed because of some incomplete -functionality. This function can be called multiple times -from the same test. - -Calling this function will not stop the test from running, you -need to return from the test function yourself. So you can -produce additional diagnostic messages or even continue running -the test. - -If not called from inside a test, this function does nothing. - - - - - - - explanation - - - - - - Initialize the GLib testing framework, e.g. by seeding the -test random number generator, the name for g_get_prgname() -and parsing test related command line args. - -So far, the following arguments are understood: - -- `-l`: List test cases available in a test executable. -- `--seed=SEED`: Provide a random seed to reproduce test - runs using random numbers. -- `--verbose`: Run tests verbosely. -- `-q`, `--quiet`: Run tests quietly. -- `-p PATH`: Execute all tests matching the given path. -- `-s PATH`: Skip all tests matching the given path. - This can also be used to force a test to run that would otherwise - be skipped (ie, a test whose name contains "/subprocess"). -- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: - - `perf`: Performance tests, may take long and report results (off by default). - - `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage - (off by default). - - `quick`: Quick tests, should run really quickly and give good coverage (the default). - - `undefined`: Tests for undefined behaviour, may provoke programming errors - under g_test_trap_subprocess() or g_test_expect_message() to check - that appropriate assertions or warnings are given (the default). - - `no-undefined`: Avoid tests for undefined behaviour - -- `--debug-log`: Debug test logging output. - -Options which can be passed to @... are: - - - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname(). - - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each - unit test and uses g_set_user_dirs() to set XDG directories to point into - that temporary directory for the duration of the unit test. See the - documentation for %G_TEST_OPTION_ISOLATE_DIRS. - -Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, -g_test_init() will print an error and exit. This is to prevent no-op tests -from being executed, as g_assert() is commonly (erroneously) used in unit -tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your -tests are compiled without `G_DISABLE_ASSERT` defined. - - - - - - - Address of the @argc parameter of the main() function. - Changed if any arguments were handled. - - - - Address of the @argv parameter of main(). - Any parameters understood by g_test_init() stripped before return. - - - - %NULL-terminated list of special options, documented below. - - - - - - Installs a non-error fatal log handler which can be -used to decide whether log messages which are counted -as fatal abort the program. - -The use case here is that you are running a test case -that depends on particular libraries or circumstances -and cannot prevent certain known critical or warning -messages. So you install a handler that compares the -domain and message to precisely not abort in such a case. - -Note that the handler is reset at the beginning of -any test case, so you have to set it inside each test -function which needs the special behavior. - -This handler has no effect on g_error messages. - -This handler also has no effect on structured log messages (using -g_log_structured() or g_log_structured_array()). To change the fatal -behaviour for specific log messages, programs must install a custom log -writer function using g_log_set_writer_func().See -[Using Structured Logging][using-structured-logging]. - - - - - - - the log handler function. - - - - data passed to the log handler. - - - - - - - - - - - - - - - - - Report the result of a performance or measurement test. -The test should generally strive to maximize the reported -quantities (larger values are better than smaller ones), -this and @maximized_quantity can determine sorting -order for test result reports. - - - - - - - the reported value - - - - the format string of the report message - - - - arguments to pass to the printf() function - - - - - - Add a message to the test report. - - - - - - - the format string - - - - printf-like arguments to @format - - - - - - Report the result of a performance or measurement test. -The test should generally strive to minimize the reported -quantities (smaller values are better than larger ones), -this and @minimized_quantity can determine sorting -order for test result reports. - - - - - - - the reported value - - - - the format string of the report message - - - - arguments to pass to the printf() function - - - - - - This function enqueus a callback @destroy_func to be executed -during the next test case teardown phase. This is most useful -to auto destruct allocated test resources at the end of a test run. -Resources are released in reverse queue order, that means enqueueing -callback A before callback B will cause B() to be called before -A() during teardown. - - - - - - - Destroy callback for teardown phase. - - - - Destroy callback data. - - - - - - Enqueue a pointer to be released with g_free() during the next -teardown phase. This is equivalent to calling g_test_queue_destroy() -with a destroy callback of g_free(). - - - - - - - the pointer to be stored. - - - - - - Enqueue an object to be released with g_object_unref() during -the next teardown phase. This is equivalent to calling -g_test_queue_destroy() with a destroy callback of g_object_unref(). - - - - the object to unref - - - - - Get a reproducible random floating point number, -see g_test_rand_int() for details on test case random numbers. - - - a random number from the seeded random number generator. - - - - - Get a reproducible random floating pointer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. - - - a number with @range_start <= number < @range_end. - - - - - the minimum value returned by this function - - - - the minimum value not returned by this function - - - - - - Get a reproducible random integer number. - -The random numbers generated by the g_test_rand_*() family of functions -change with every new test program start, unless the --seed option is -given when starting test programs. - -For individual test cases however, the random number generator is -reseeded, to avoid dependencies between tests and to make --seed -effective for all test cases. - - - a random number from the seeded random number generator. - - - - - Get a reproducible random integer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. - - - a number with @begin <= number < @end. - - - - - the minimum value returned by this function - - - - the smallest value not to be returned by this function - - - - - - Runs all tests under the toplevel suite which can be retrieved -with g_test_get_root(). Similar to g_test_run_suite(), the test -cases to be run are filtered according to test path arguments -(`-p testpath` and `-s testpath`) as parsed by g_test_init(). -g_test_run_suite() or g_test_run() may only be called once in a -program. - -In general, the tests and sub-suites within each suite are run in -the order in which they are defined. However, note that prior to -GLib 2.36, there was a bug in the `g_test_add_*` -functions which caused them to create multiple suites with the same -name, meaning that if you created tests "/foo/simple", -"/bar/simple", and "/foo/using-bar" in that order, they would get -run in that order (since g_test_run() would run the first "/foo" -suite, then the "/bar" suite, then the second "/foo" suite). As of -2.36, this bug is fixed, and adding the tests in that order would -result in a running order of "/foo/simple", "/foo/using-bar", -"/bar/simple". If this new ordering is sub-optimal (because it puts -more-complicated tests before simpler ones, making it harder to -figure out exactly what has failed), you can fix it by changing the -test paths to group tests by suite in a way that will result in the -desired running order. Eg, "/simple/foo", "/simple/bar", -"/complex/foo-using-bar". - -However, you should never make the actual result of a test depend -on the order that tests are run in. If you need to ensure that some -particular code runs before or after a given test case, use -g_test_add(), which lets you specify setup and teardown functions. - -If all tests are skipped or marked as incomplete (expected failures), -this function will return 0 if producing TAP output, or 77 (treated -as "skip test" by Automake) otherwise. - - - 0 on success, 1 on failure (assuming it returns at all), - 0 or 77 if all tests were skipped with g_test_skip() and/or - g_test_incomplete() - - - - - Execute the tests within @suite and all nested #GTestSuites. -The test suites to be executed are filtered according to -test path arguments (`-p testpath` and `-s testpath`) as parsed by -g_test_init(). See the g_test_run() documentation for more -information on the order that tests are run in. - -g_test_run_suite() or g_test_run() may only be called once -in a program. - - - 0 on success - - - - - a #GTestSuite - - - - - - Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), -g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), -g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), -g_assert_error(), g_test_assert_expected_messages() and the various -g_test_trap_assert_*() macros to not abort to program, but instead -call g_test_fail() and continue. (This also changes the behavior of -g_test_fail() so that it will not cause the test program to abort -after completing the failed test.) - -Note that the g_assert_not_reached() and g_assert() are not -affected by this. - -This function can only be called after g_test_init(). - - - - - - - Indicates that a test was skipped. - -Calling this function will not stop the test from running, you -need to return from the test function yourself. So you can -produce additional diagnostic messages or even continue running -the test. - -If not called from inside a test, this function does nothing. - - - - - - - explanation - - - - - - Returns %TRUE (after g_test_init() has been called) if the test -program is running under g_test_trap_subprocess(). - - - %TRUE if the test program is running under -g_test_trap_subprocess(). - - - - - Set the summary for a test, which describes what the test checks, and how it -goes about checking it. This may be included in test report output, and is -useful documentation for anyone reading the source code or modifying a test -in future. It must be a single line. - -This should be called at the top of a test function. - -For example: -|[<!-- language="C" --> -static void -test_array_sort (void) -{ - g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " - "including testing zero length and one-element arrays."); - - … -} -]| - -See also: g_test_bug() - - - - - - - One or two sentences summarising what the test checks, and how it - checks it. - - - - - - Get the time since the last start of the timer with g_test_timer_start(). - - - the time since the last start of the timer, as a double - - - - - Report the last result of g_test_timer_elapsed(). - - - the last result of g_test_timer_elapsed(), as a double - - - - - Start a timing test. Call g_test_timer_elapsed() when the task is supposed -to be done. Call this function again to restart the timer. - - - - - - - Assert that the stderr output of the last test subprocess -matches @serrpattern. See g_test_trap_subprocess(). - -This is sometimes used to test situations that are formally -considered to be undefined behaviour, like code that hits a -g_assert() or g_error(). In these situations you should skip the -entire test, including the call to g_test_trap_subprocess(), unless -g_test_undefined() returns %TRUE to indicate that undefined -behaviour may be tested. - - - - a glob-style [pattern][glib-Glob-style-pattern-matching] - - - - - Assert that the stderr output of the last test subprocess -does not match @serrpattern. See g_test_trap_subprocess(). - - - - a glob-style [pattern][glib-Glob-style-pattern-matching] - - - - - Assert that the stdout output of the last test subprocess matches -@soutpattern. See g_test_trap_subprocess(). - - - - a glob-style [pattern][glib-Glob-style-pattern-matching] - - - - - Assert that the stdout output of the last test subprocess -does not match @soutpattern. See g_test_trap_subprocess(). - - - - a glob-style [pattern][glib-Glob-style-pattern-matching] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Fork the current test program to execute a test case that might -not return or that might abort. - -If @usec_timeout is non-0, the forked test case is aborted and -considered failing if its run time exceeds it. - -The forking behavior can be configured with the #GTestTrapFlags flags. - -In the following example, the test code forks, the forked child -process produces some sample output and exits successfully. -The forking parent process then asserts successful child program -termination and validates child program outputs. - -|[<!-- language="C" --> - static void - test_fork_patterns (void) - { - if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) - { - g_print ("some stdout text: somagic17\n"); - g_printerr ("some stderr text: semagic43\n"); - exit (0); // successful test run - } - g_test_trap_assert_passed (); - g_test_trap_assert_stdout ("*somagic17*"); - g_test_trap_assert_stderr ("*semagic43*"); - } -]| - This function is implemented only on Unix platforms, -and is not always reliable due to problems inherent in -fork-without-exec. Use g_test_trap_subprocess() instead. - - - %TRUE for the forked child and %FALSE for the executing parent process. - - - - - Timeout for the forked test in micro seconds. - - - - Flags to modify forking behaviour. - - - - - - Check the result of the last g_test_trap_subprocess() call. - - - %TRUE if the last test subprocess terminated successfully. - - - - - Check the result of the last g_test_trap_subprocess() call. - - - %TRUE if the last test subprocess got killed due to a timeout. - - - - - Respawns the test program to run only @test_path in a subprocess. -This can be used for a test case that might not return, or that -might abort. - -If @test_path is %NULL then the same test is re-run in a subprocess. -You can use g_test_subprocess() to determine whether the test is in -a subprocess or not. - -@test_path can also be the name of the parent test, followed by -"`/subprocess/`" and then a name for the specific subtest (or just -ending with "`/subprocess`" if the test only has one child test); -tests with names of this form will automatically be skipped in the -parent process. - -If @usec_timeout is non-0, the test subprocess is aborted and -considered failing if its run time exceeds it. - -The subprocess behavior can be configured with the -#GTestSubprocessFlags flags. - -You can use methods such as g_test_trap_assert_passed(), -g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to -check the results of the subprocess. (But note that -g_test_trap_assert_stdout() and g_test_trap_assert_stderr() -cannot be used if @test_flags specifies that the child should -inherit the parent stdout/stderr.) - -If your `main ()` needs to behave differently in -the subprocess, you can call g_test_subprocess() (after calling -g_test_init()) to see whether you are in a subprocess. - -The following example tests that calling -`my_object_new(1000000)` will abort with an error -message. - -|[<!-- language="C" --> - static void - test_create_large_object (void) - { - if (g_test_subprocess ()) - { - my_object_new (1000000); - return; - } - - // Reruns this same test in a subprocess - g_test_trap_subprocess (NULL, 0, 0); - g_test_trap_assert_failed (); - g_test_trap_assert_stderr ("*ERROR*too large*"); - } - - int - main (int argc, char **argv) - { - g_test_init (&argc, &argv, NULL); - - g_test_add_func ("/myobject/create_large_object", - test_create_large_object); - return g_test_run (); - } -]| - - - - - - - Test to run in a subprocess - - - - Timeout for the subprocess test in micro seconds. - - - - Flags to modify subprocess behaviour. - - - - - - - - - - - Terminates the current thread. - -If another thread is waiting for us using g_thread_join() then the -waiting thread will be woken up and get @retval as the return value -of g_thread_join(). - -Calling g_thread_exit() with a parameter @retval is equivalent to -returning @retval from the function @func, as given to g_thread_new(). - -You must only call g_thread_exit() from a thread that you created -yourself with g_thread_new() or related APIs. You must not call -this function from a thread created with another threading library -or or from within a #GThreadPool. - - - - - - - the return value of this thread - - - - - - This function will return the maximum @interval that a -thread will wait in the thread pool for new tasks before -being stopped. - -If this function returns 0, threads waiting in the thread -pool for new work are not stopped. - - - the maximum @interval (milliseconds) to wait - for new tasks in the thread pool before stopping the - thread - - - - - Returns the maximal allowed number of unused threads. - - - the maximal number of unused threads - - - - - Returns the number of currently unused threads. - - - the number of currently unused threads - - - - - This function will set the maximum @interval that a thread -waiting in the pool for new tasks can be idle for before -being stopped. This function is similar to calling -g_thread_pool_stop_unused_threads() on a regular timeout, -except this is done on a per thread basis. - -By setting @interval to 0, idle threads will not be stopped. - -The default value is 15000 (15 seconds). - - - - - - - the maximum @interval (in milliseconds) - a thread can be idle - - - - - - Sets the maximal number of unused threads to @max_threads. -If @max_threads is -1, no limit is imposed on the number -of unused threads. - -The default value is 2. - - - - - - - maximal number of unused threads - - - - - - Stops all currently unused threads. This does not change the -maximal number of unused threads. This function can be used to -regularly stop all unused threads e.g. from g_timeout_add(). - - - - - - - This function returns the #GThread corresponding to the -current thread. Note that this function does not increase -the reference count of the returned struct. - -This function will return a #GThread even for threads that -were not created by GLib (i.e. those created by other threading -APIs). This may be useful for thread identification purposes -(i.e. comparisons) but you must not use GLib functions (such -as g_thread_join()) on these threads. - - - the #GThread representing the current thread - - - - - Causes the calling thread to voluntarily relinquish the CPU, so -that other threads can run. - -This function is often used as a method to make busy wait less evil. - - - - - - - Converts a string containing an ISO 8601 encoded date and time -to a #GTimeVal and puts it into @time_. - -@iso_date must include year, month, day, hours, minutes, and -seconds. It can optionally include fractions of a second and a time -zone indicator. (In the absence of any time zone indication, the -timestamp is assumed to be in local time.) - -Any leading or trailing space in @iso_date is ignored. - -This function was deprecated, along with #GTimeVal itself, in GLib 2.62. -Equivalent functionality is available using code like: -|[ -GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL); -gint64 time_val = g_date_time_to_unix (dt); -g_date_time_unref (dt); -]| - #GTimeVal is not year-2038-safe. Use - g_date_time_new_from_iso8601() instead. - - - %TRUE if the conversion was successful. - - - - - an ISO 8601 encoded date string - - - - a #GTimeVal - - - - - - Sets a function to be called at regular intervals, with the default -priority, #G_PRIORITY_DEFAULT. The function is called repeatedly -until it returns %FALSE, at which point the timeout is automatically -destroyed and the function will not be called again. The first call -to the function will be at the end of the first @interval. - -Note that timeout functions may be delayed, due to the processing of other -event sources. Thus they should not be relied on for precise timing. -After each call to the timeout function, the time of the next -timeout is recalculated based on the current time and the given interval -(it does not try to 'catch up' time lost in delays). - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -If you want to have a timer in the "seconds" range and do not care -about the exact time of the first call of the timer, use the -g_timeout_add_seconds() function; this function allows for more -optimizations and more efficient system power usage. - -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - -It is safe to call this function from any thread. - -The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - - - the ID (greater than 0) of the event source. - - - - - the time between calls to the function, in milliseconds - (1/1000ths of a second) - - - - function to call - - - - data to pass to @function - - - - - - Sets a function to be called at regular intervals, with the given -priority. The function is called repeatedly until it returns -%FALSE, at which point the timeout is automatically destroyed and -the function will not be called again. The @notify function is -called when the timeout is destroyed. The first call to the -function will be at the end of the first @interval. - -Note that timeout functions may be delayed, due to the processing of other -event sources. Thus they should not be relied on for precise timing. -After each call to the timeout function, the time of the next -timeout is recalculated based on the current time and the given interval -(it does not try to 'catch up' time lost in delays). - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. - -The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). - - - the ID (greater than 0) of the event source. - - - - - the priority of the timeout source. Typically this will be in - the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - - - - the time between calls to the function, in milliseconds - (1/1000ths of a second) - - - - function to call - - - - data to pass to @function - - - - function to call when the timeout is removed, or %NULL - - - - - - Sets a function to be called at regular intervals with the default -priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until -it returns %FALSE, at which point the timeout is automatically destroyed -and the function will not be called again. - -This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. Also see g_timeout_add_seconds_full(). - -It is safe to call this function from any thread. - -Note that the first call of the timer may not be precise for timeouts -of one second. If you need finer precision and have such a timeout, -you may want to use g_timeout_add() instead. - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - - - the ID (greater than 0) of the event source. - - - - - the time between calls to the function, in seconds - - - - function to call - - - - data to pass to @function - - - - - - Sets a function to be called at regular intervals, with @priority. -The function is called repeatedly until it returns %FALSE, at which -point the timeout is automatically destroyed and the function will -not be called again. - -Unlike g_timeout_add(), this function operates at whole second granularity. -The initial starting point of the timer is determined by the implementation -and the implementation is expected to group multiple timers together so that -they fire all at the same time. -To allow this grouping, the @interval to the first timer is rounded -and can deviate up to one second from the specified interval. -Subsequent timer iterations will generally run at the specified interval. - -Note that timeout functions may be delayed, due to the processing of other -event sources. Thus they should not be relied on for precise timing. -After each call to the timeout function, the time of the next -timeout is recalculated based on the current time and the given @interval - -See [memory management of sources][mainloop-memory-management] for details -on how to handle the return value and memory management of @data. - -If you want timing more precise than whole seconds, use g_timeout_add() -instead. - -The grouping of timers to fire at the same time results in a more power -and CPU efficient behavior so if your timer is in multiples of seconds -and you don't require the first timer exactly one second from now, the -use of g_timeout_add_seconds() is preferred over g_timeout_add(). - -This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. - -It is safe to call this function from any thread. - -The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - - - the ID (greater than 0) of the event source. - - - - - the priority of the timeout source. Typically this will be in - the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - - - - the time between calls to the function, in seconds - - - - function to call - - - - data to pass to @function - - - - function to call when the timeout is removed, or %NULL - - - - - - Creates a new timeout source. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. - -The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). - - - the newly-created timeout source - - - - - the timeout interval in milliseconds. - - - - - - Creates a new timeout source. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. - -The scheduling granularity/accuracy of this timeout source will be -in seconds. - -The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). - - - the newly-created timeout source - - - - - the timeout interval in seconds - - - - - - Returns the height of a #GTrashStack. - -Note that execution of this function is of O(N) complexity -where N denotes the number of items on the stack. - #GTrashStack is deprecated without replacement - - - the height of the stack - - - - - a #GTrashStack - - - - - - Returns the element at the top of a #GTrashStack -which may be %NULL. - #GTrashStack is deprecated without replacement - - - the element at the top of the stack - - - - - a #GTrashStack - - - - - - Pops a piece of memory off a #GTrashStack. - #GTrashStack is deprecated without replacement - - - the element at the top of the stack - - - - - a #GTrashStack - - - - - - Pushes a piece of memory onto a #GTrashStack. - #GTrashStack is deprecated without replacement - - - - - - - a #GTrashStack - - - - the piece of memory to push on the stack - - - - - - Attempts to allocate @n_bytes, and returns %NULL on failure. -Contrast with g_malloc(), which aborts the program on failure. - - - the allocated memory, or %NULL. - - - - - number of bytes to allocate. - - - - - - Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on -failure. Contrast with g_malloc0(), which aborts the program on failure. - - - the allocated memory, or %NULL - - - - - number of bytes to allocate - - - - - - This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - the allocated memory, or %NULL - - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - the allocated memory, or %NULL. - - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - Attempts to allocate @n_structs elements of type @struct_type, and returns -%NULL on failure. Contrast with g_new(), which aborts the program on failure. -The returned pointer is cast to a pointer to the given type. -The function returns %NULL when @n_structs is 0 of if an overflow occurs. - - - - the type of the elements to allocate - - - the number of elements to allocate - - - - - Attempts to allocate @n_structs elements of type @struct_type, initialized -to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts -the program on failure. -The returned pointer is cast to a pointer to the given type. -The function returns %NULL when @n_structs is 0 or if an overflow occurs. - - - - the type of the elements to allocate - - - the number of elements to allocate - - - - - Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL -on failure. Contrast with g_realloc(), which aborts the program -on failure. - -If @mem is %NULL, behaves the same as g_try_malloc(). - - - the allocated memory, or %NULL. - - - - - previously-allocated memory, or %NULL. - - - - number of bytes to allocate. - - - - - - This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - - the allocated memory, or %NULL. - - - - - previously-allocated memory, or %NULL. - - - - the number of blocks to allocate - - - - the size of each block in bytes - - - - - - Attempts to reallocate the memory pointed to by @mem, so that it now has -space for @n_structs elements of type @struct_type, and returns %NULL on -failure. Contrast with g_renew(), which aborts the program on failure. -It returns the new address of the memory, which may have been moved. -The function returns %NULL if an overflow occurs. - - - - the type of the elements to allocate - - - the currently allocated memory - - - the number of elements to allocate - - - - - Convert a string from UCS-4 to UTF-16. A 0 character will be -added to the result after the converted text. - - - a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. - - - - - a UCS-4 encoded string - - - - the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. - - - - location to store number of - bytes read, or %NULL. If an error occurs then the index of the invalid - input is stored here. - - - - location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. - - - - - - Convert a string from a 32-bit fixed width representation as UCS-4. -to UTF-8. The result will be terminated with a 0 byte. - - - a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. In that case, @items_read - will be set to the position of the first invalid input character. - - - - - a UCS-4 encoded string - - - - the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. - - - - location to store number of - characters read, or %NULL. - - - - location to store number - of bytes written or %NULL. The value here stored does not include the - trailing 0 byte. - - - - - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #guint64 destination - - - the #guint64 left operand - - - the #guint64 right operand - - - - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #guint64 destination - - - the #guint64 left operand - - - the #guint64 right operand - - - - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #guint destination - - - the #guint left operand - - - the #guint right operand - - - - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. - - - - a pointer to the #guint destination - - - the #guint left operand - - - the #guint right operand - - - - - Determines the break type of @c. @c should be a Unicode character -(to derive a character from UTF-8 encoded text, use -g_utf8_get_char()). The break type is used to find word and line -breaks ("text boundaries"), Pango implements the Unicode boundary -resolution algorithms and normally you would use a function such -as pango_break() instead of caring about break types yourself. - - - the break type of @c - - - - - a Unicode character - - - - - - Determines the canonical combining class of a Unicode character. - - - the combining class of the character - - - - - a Unicode character - - - - - - Performs a single composition step of the -Unicode canonical composition algorithm. - -This function includes algorithmic Hangul Jamo composition, -but it is not exactly the inverse of g_unichar_decompose(). -No composition can have either of @a or @b equal to zero. -To be precise, this function composes if and only if -there exists a Primary Composite P which is canonically -equivalent to the sequence <@a,@b>. See the Unicode -Standard for the definition of Primary Composite. - -If @a and @b do not compose a new character, @ch is set to zero. - -See -[UAX#15](http://unicode.org/reports/tr15/) -for details. - - - %TRUE if the characters could be composed - - - - - a Unicode character - - - - a Unicode character - - - - return location for the composed character - - - - - - Performs a single decomposition step of the -Unicode canonical decomposition algorithm. - -This function does not include compatibility -decompositions. It does, however, include algorithmic -Hangul Jamo decomposition, as well as 'singleton' -decompositions which replace a character by a single -other character. In the case of singletons *@b will -be set to zero. - -If @ch is not decomposable, *@a is set to @ch and *@b -is set to zero. - -Note that the way Unicode decomposition pairs are -defined, it is guaranteed that @b would not decompose -further, but @a may itself decompose. To get the full -canonical decomposition for @ch, one would need to -recursively call this function on @a. Or use -g_unichar_fully_decompose(). - -See -[UAX#15](http://unicode.org/reports/tr15/) -for details. - - - %TRUE if the character could be decomposed - - - - - a Unicode character - - - - return location for the first component of @ch - - - - return location for the second component of @ch - - - - - - Determines the numeric value of a character as a decimal -digit. - - - If @c is a decimal digit (according to -g_unichar_isdigit()), its numeric value. Otherwise, -1. - - - - - a Unicode character - - - - - - Computes the canonical or compatibility decomposition of a -Unicode character. For compatibility decomposition, -pass %TRUE for @compat; for canonical decomposition -pass %FALSE for @compat. - -The decomposed sequence is placed in @result. Only up to -@result_len characters are written into @result. The length -of the full decomposition (irrespective of @result_len) is -returned by the function. For canonical decomposition, -currently all decompositions are of length at most 4, but -this may change in the future (very unlikely though). -At any rate, Unicode does guarantee that a buffer of length -18 is always enough for both compatibility and canonical -decompositions, so that is the size recommended. This is provided -as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. - -See -[UAX#15](http://unicode.org/reports/tr15/) -for details. - - - the length of the full decomposition. - - - - - a Unicode character. - - - - whether perform canonical or compatibility decomposition - - - - location to store decomposed result, or %NULL - - - - length of @result - - - - - - In Unicode, some characters are "mirrored". This means that their -images are mirrored horizontally in text that is laid out from right -to left. For instance, "(" would become its mirror image, ")", in -right-to-left text. - -If @ch has the Unicode mirrored property and there is another unicode -character that typically has a glyph that is the mirror image of @ch's -glyph and @mirrored_ch is set, it puts that character in the address -pointed to by @mirrored_ch. Otherwise the original character is put. - - - %TRUE if @ch has a mirrored character, %FALSE otherwise - - - - - a Unicode character - - - - location to store the mirrored character - - - - - - Looks up the #GUnicodeScript for a particular character (as defined -by Unicode Standard Annex \#24). No check is made for @ch being a -valid Unicode character; if you pass in invalid character, the -result is undefined. - -This function is equivalent to pango_script_for_unichar() and the -two are interchangeable. - - - the #GUnicodeScript for the character. - - - - - a Unicode character - - - - - - Determines whether a character is alphanumeric. -Given some UTF-8 text, obtain a character value -with g_utf8_get_char(). - - - %TRUE if @c is an alphanumeric character - - - - - a Unicode character - - - - - - Determines whether a character is alphabetic (i.e. a letter). -Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is an alphabetic character - - - - - a Unicode character - - - - - - Determines whether a character is a control character. -Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is a control character - - - - - a Unicode character - - - - - - Determines if a given character is assigned in the Unicode -standard. - - - %TRUE if the character has an assigned value - - - - - a Unicode character - - - - - - Determines whether a character is numeric (i.e. a digit). This -covers ASCII 0-9 and also digits in other languages/scripts. Given -some UTF-8 text, obtain a character value with g_utf8_get_char(). - - - %TRUE if @c is a digit - - - - - a Unicode character - - - - - - Determines whether a character is printable and not a space -(returns %FALSE for control characters, format characters, and -spaces). g_unichar_isprint() is similar, but returns %TRUE for -spaces. Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is printable unless it's a space - - - - - a Unicode character - - - - - - Determines whether a character is a lowercase letter. -Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is a lowercase letter - - - - - a Unicode character - - - - - - Determines whether a character is a mark (non-spacing mark, -combining mark, or enclosing mark in Unicode speak). -Given some UTF-8 text, obtain a character value -with g_utf8_get_char(). - -Note: in most cases where isalpha characters are allowed, -ismark characters should be allowed to as they are essential -for writing most European languages as well as many non-Latin -scripts. - - - %TRUE if @c is a mark character - - - - - a Unicode character - - - - - - Determines whether a character is printable. -Unlike g_unichar_isgraph(), returns %TRUE for spaces. -Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is printable - - - - - a Unicode character - - - - - - Determines whether a character is punctuation or a symbol. -Given some UTF-8 text, obtain a character value with -g_utf8_get_char(). - - - %TRUE if @c is a punctuation or symbol character - - - - - a Unicode character - - - - - - Determines whether a character is a space, tab, or line separator -(newline, carriage return, etc.). Given some UTF-8 text, obtain a -character value with g_utf8_get_char(). - -(Note: don't use this to do word breaking; you have to use -Pango or equivalent to get word breaking right, the algorithm -is fairly complex.) - - - %TRUE if @c is a space character - - - - - a Unicode character - - - - - - Determines if a character is titlecase. Some characters in -Unicode which are composites, such as the DZ digraph -have three case variants instead of just two. The titlecase -form is used at the beginning of a word where only the -first letter is capitalized. The titlecase form of the DZ -digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. - - - %TRUE if the character is titlecase - - - - - a Unicode character - - - - - - Determines if a character is uppercase. - - - %TRUE if @c is an uppercase character - - - - - a Unicode character - - - - - - Determines if a character is typically rendered in a double-width -cell. - - - %TRUE if the character is wide - - - - - a Unicode character - - - - - - Determines if a character is typically rendered in a double-width -cell under legacy East Asian locales. If a character is wide according to -g_unichar_iswide(), then it is also reported wide with this function, but -the converse is not necessarily true. See the -[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) -for details. - -If a character passes the g_unichar_iswide() test then it will also pass -this test, but not the other way around. Note that some characters may -pass both this test and g_unichar_iszerowidth(). - - - %TRUE if the character is wide in legacy East Asian locales - - - - - a Unicode character - - - - - - Determines if a character is a hexidecimal digit. - - - %TRUE if the character is a hexadecimal digit - - - - - a Unicode character. - - - - - - Determines if a given character typically takes zero width when rendered. -The return value is %TRUE for all non-spacing and enclosing marks -(e.g., combining accents), format characters, zero-width -space, but not U+00AD SOFT HYPHEN. - -A typical use of this function is with one of g_unichar_iswide() or -g_unichar_iswide_cjk() to determine the number of cells a string occupies -when displayed on a grid display (terminals). However, note that not all -terminals support zero-width rendering of zero-width marks. - - - %TRUE if the character has zero width - - - - - a Unicode character - - - - - - Converts a single character to UTF-8. - - - number of bytes written - - - - - a Unicode character code - - - - output buffer, must have at - least 6 bytes of space. If %NULL, the length will be computed and - returned and nothing will be written to @outbuf. - - - - - - Converts a character to lower case. - - - the result of converting @c to lower case. - If @c is not an upperlower or titlecase character, - or has no lowercase equivalent @c is returned unchanged. - - - - - a Unicode character. - - - - - - Converts a character to the titlecase. - - - the result of converting @c to titlecase. - If @c is not an uppercase or lowercase character, - @c is returned unchanged. - - - - - a Unicode character - - - - - - Converts a character to uppercase. - - - the result of converting @c to uppercase. - If @c is not a lowercase or titlecase character, - or has no upper case equivalent @c is returned unchanged. - - - - - a Unicode character - - - - - - Classifies a Unicode character by type. - - - the type of the character. - - - - - a Unicode character - - - - - - Checks whether @ch is a valid Unicode character. Some possible -integer values of @ch will not be valid. 0 is considered a valid -character, though it's normally a string terminator. - - - %TRUE if @ch is a valid Unicode character - - - - - a Unicode character - - - - - - Determines the numeric value of a character as a hexidecimal -digit. - - - If @c is a hex digit (according to -g_unichar_isxdigit()), its numeric value. Otherwise, -1. - - - - - a Unicode character - - - - - - Computes the canonical decomposition of a Unicode character. - Use the more flexible g_unichar_fully_decompose() - instead. - - - a newly allocated string of Unicode characters. - @result_len is set to the resulting length of the string. - - - - - a Unicode character. - - - - location to store the length of the return value. - - - - - - Computes the canonical ordering of a string in-place. -This rearranges decomposed characters in the string -according to their combining classes. See the Unicode -manual for more information. - - - - - - - a UCS-4 encoded string. - - - - the maximum length of @string to use. - - - - - - Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter -codes to scripts. For example, the code for Arabic is 'Arab'. -This function accepts four letter codes encoded as a @guint32 in a -big-endian fashion. That is, the code expected for Arabic is -0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). - -See -[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) -for details. - - - the Unicode script for @iso15924, or - of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and - %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. - - - - - a Unicode script - - - - - - Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter -codes to scripts. For example, the code for Arabic is 'Arab'. The -four letter codes are encoded as a @guint32 by this function in a -big-endian fashion. That is, the code returned for Arabic is -0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). - -See -[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) -for details. - - - the ISO 15924 code for @script, encoded as an integer, - of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or - ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. - - - - - a Unicode script - - - - - - - - - - - Sets a function to be called when the IO condition, as specified by -@condition becomes true for @fd. - -@function will be called when the specified IO condition becomes -%TRUE. The function is expected to clear whatever event caused the -IO condition to become true and return %TRUE in order to be notified -when it happens again. If @function returns %FALSE then the watch -will be cancelled. - -The return value of this function can be passed to g_source_remove() -to cancel the watch at any time that it exists. - -The source will never close the fd -- you must do it yourself. - - - the ID (greater than 0) of the event source - - - - - a file descriptor - - - - IO conditions to watch for on @fd - - - - a #GUnixFDSourceFunc - - - - data to pass to @function - - - - - - Sets a function to be called when the IO condition, as specified by -@condition becomes true for @fd. - -This is the same as g_unix_fd_add(), except that it allows you to -specify a non-default priority and a provide a #GDestroyNotify for -@user_data. - - - the ID (greater than 0) of the event source - - - - - the priority of the source - - - - a file descriptor - - - - IO conditions to watch for on @fd - - - - a #GUnixFDSourceFunc - - - - data to pass to @function - - - - function to call when the idle is removed, or %NULL - - - - - - Creates a #GSource to watch for a particular IO condition on a file -descriptor. - -The source will never close the fd -- you must do it yourself. - - - the newly created #GSource - - - - - a file descriptor - - - - IO conditions to watch for on @fd - - - - - - Get the `passwd` file entry for the given @user_name using `getpwnam_r()`. -This can fail if the given @user_name doesn’t exist. - -The returned `struct passwd` has been allocated using g_malloc() and should -be freed using g_free(). The strings referenced by the returned struct are -included in the same allocation, so are valid until the `struct passwd` is -freed. - -This function is safe to call from multiple threads concurrently. - -You will need to include `pwd.h` to get the definition of `struct passwd`. - - - passwd entry, or %NULL on error; free the returned - value with g_free() - - - - - the username to get the passwd file entry for - - - - - - Similar to the UNIX pipe() call, but on modern systems like Linux -uses the pipe2() system call, which atomically creates a pipe with -the configured flags. The only supported flag currently is -%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that -must still be done separately with fcntl(). - -This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if -for fcntl(); these are different on Linux/glibc. - - - %TRUE on success, %FALSE if not (and errno will be set). - - - - - Array of two integers - - - - Bitfield of file descriptor flags, as for fcntl() - - - - - - Control the non-blocking state of the given file descriptor, -according to @nonblock. On most systems this uses %O_NONBLOCK, but -on some older ones may use %O_NDELAY. - - - %TRUE if successful - - - - - A file descriptor - - - - If %TRUE, set the descriptor to be non-blocking - - - - - - A convenience function for g_unix_signal_source_new(), which -attaches to the default #GMainContext. You can remove the watch -using g_source_remove(). - - - An ID (greater than 0) for the event source - - - - - Signal number - - - - Callback - - - - Data for @handler - - - - - - A convenience function for g_unix_signal_source_new(), which -attaches to the default #GMainContext. You can remove the watch -using g_source_remove(). - - - An ID (greater than 0) for the event source - - - - - the priority of the signal source. Typically this will be in - the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - - - - Signal number - - - - Callback - - - - Data for @handler - - - - #GDestroyNotify for @handler - - - - - - Create a #GSource that will be dispatched upon delivery of the UNIX -signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, -`SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` -were added. In GLib 2.54, `SIGWINCH` was added. - -Note that unlike the UNIX default, all sources which have created a -watch will be dispatched, regardless of which underlying thread -invoked g_unix_signal_source_new(). - -For example, an effective use of this function is to handle `SIGTERM` -cleanly; flushing any outstanding files, and then calling -g_main_loop_quit (). It is not safe to do any of this a regular -UNIX signal handler; your handler may be invoked while malloc() or -another library function is running, causing reentrancy if you -attempt to use it from the handler. None of the GLib/GObject API -is safe against this kind of reentrancy. - -The interaction of this source when combined with native UNIX -functions like sigprocmask() is not defined. - -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. - - - A newly created #GSource - - - - - A signal number - - - - - - A wrapper for the POSIX unlink() function. The unlink() function -deletes a name from the filesystem. If this was the last link to the -file and no processes have it opened, the diskspace occupied by the -file is freed. - -See your C library manual for more details about unlink(). Note -that on Windows, it is in general not possible to delete files that -are open to some process, or mapped into memory. - - - 0 if the name was successfully deleted, -1 if an error - occurred - - - - - a pathname in the GLib file name encoding - (UTF-8 on Windows) - - - - - - Removes an environment variable from the environment. - -Note that on some systems, when variables are overwritten, the -memory used for the previous variables and its value isn't reclaimed. - -You should be mindful of the fact that environment variable handling -in UNIX is not thread-safe, and your program may crash if one thread -calls g_unsetenv() while another thread is calling getenv(). (And note -that many functions, such as gettext(), call getenv() internally.) This -function is only safe to use at the very start of your program, before -creating any other threads (or creating objects that create worker -threads of their own). - -If you need to set up the environment for a child process, you can -use g_get_environ() to get an environment array, modify that with -g_environ_setenv() and g_environ_unsetenv(), and then pass that -array directly to execvpe(), g_spawn_async(), or the like. - - - - - - - the environment variable to remove, must - not contain '=' - - - - - - Escapes a string for use in a URI. - -Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical -characters plus dash, dot, underscore and tilde) are escaped. -But if you specify characters in @reserved_chars_allowed they are not -escaped. This is useful for the "reserved" characters in the URI -specification, since those are allowed unescaped in some portions of -a URI. - - - an escaped version of @unescaped. The returned string should be -freed when no longer needed. - - - - - the unescaped input string. - - - - a string of reserved characters that - are allowed to be used, or %NULL. - - - - %TRUE if the result can include UTF-8 characters. - - - - - - Splits an URI list conforming to the text/uri-list -mime type defined in RFC 2483 into individual URIs, -discarding any comments. The URIs are not validated. - - - a newly allocated %NULL-terminated list - of strings holding the individual URIs. The array should be freed - with g_strfreev(). - - - - - - - an URI list - - - - - - Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: -|[ -URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] -]| -Common schemes include "file", "http", "svn+ssh", etc. - - - The "Scheme" component of the URI, or %NULL on error. -The returned string should be freed when no longer needed. - - - - - a valid URI. - - - - - - Unescapes a segment of an escaped string. - -If any of the characters in @illegal_characters or the character zero appears -as an escaped character in @escaped_string then that is an error and %NULL -will be returned. This is useful it you want to avoid for instance having a -slash being expanded in an escaped path element, which might confuse pathname -handling. - - - an unescaped version of @escaped_string or %NULL on error. -The returned string should be freed when no longer needed. As a -special case if %NULL is given for @escaped_string, this function -will return %NULL. - - - - - A string, may be %NULL - - - - Pointer to end of @escaped_string, may be %NULL - - - - An optional string of illegal characters not to be allowed, may be %NULL - - - - - - Unescapes a whole escaped string. - -If any of the characters in @illegal_characters or the character zero appears -as an escaped character in @escaped_string then that is an error and %NULL -will be returned. This is useful it you want to avoid for instance having a -slash being expanded in an escaped path element, which might confuse pathname -handling. - - - an unescaped version of @escaped_string. The returned string -should be freed when no longer needed. - - - - - an escaped string to be unescaped. - - - - a string of illegal characters not to be - allowed, or %NULL. - - - - - - Pauses the current thread for the given number of microseconds. - -There are 1 million microseconds per second (represented by the -#G_USEC_PER_SEC macro). g_usleep() may have limited precision, -depending on hardware and operating system; don't rely on the exact -length of the sleep. - - - - - - - number of microseconds to pause - - - - - - Convert a string from UTF-16 to UCS-4. The result will be -nul-terminated. - - - a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. - - - - - a UTF-16 encoded string - - - - the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. - - - - location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. - - - - location to store number - of characters written, or %NULL. The value stored here does not include - the trailing 0 character. - - - - - - Convert a string from UTF-16 to UTF-8. The result will be -terminated with a 0 byte. - -Note that the input is expected to be already in native endianness, -an initial byte-order-mark character is not handled specially. -g_convert() can be used to convert a byte buffer of UTF-16 data of -ambiguous endianess. - -Further note that this function does not validate the result -string; it may e.g. include embedded NUL characters. The only -validation done by this function is to ensure that the input can -be correctly interpreted as UTF-16, i.e. it doesn't contain -things unpaired surrogates. - - - a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. - - - - - a UTF-16 encoded string - - - - the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. - - - - location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. - - - - location to store number - of bytes written, or %NULL. The value stored here does not include the - trailing 0 byte. - - - - - - Converts a string into a form that is independent of case. The -result will not correspond to any particular case, but can be -compared for equality or ordered with the results of calling -g_utf8_casefold() on other strings. - -Note that calling g_utf8_casefold() followed by g_utf8_collate() is -only an approximation to the correct linguistic case insensitive -ordering, though it is a fairly good one. Getting this exactly -right would require a more sophisticated collation function that -takes case sensitivity into account. GLib does not currently -provide such a function. - - - a newly allocated string, that is a - case independent form of @str. - - - - - a UTF-8 encoded string - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - - - Compares two strings for ordering using the linguistically -correct rules for the [current locale][setlocale]. -When sorting a large number of strings, it will be significantly -faster to obtain collation keys with g_utf8_collate_key() and -compare the keys with strcmp() when sorting instead of sorting -the original strings. - - - < 0 if @str1 compares before @str2, - 0 if they compare equal, > 0 if @str1 compares after @str2. - - - - - a UTF-8 encoded string - - - - a UTF-8 encoded string - - - - - - Converts a string into a collation key that can be compared -with other collation keys produced by the same function using -strcmp(). - -The results of comparing the collation keys of two strings -with strcmp() will always be the same as comparing the two -original keys with g_utf8_collate(). - -Note that this function depends on the [current locale][setlocale]. - - - a newly allocated string. This string should - be freed with g_free() when you are done with it. - - - - - a UTF-8 encoded string. - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - - - Converts a string into a collation key that can be compared -with other collation keys produced by the same function using strcmp(). - -In order to sort filenames correctly, this function treats the dot '.' -as a special case. Most dictionary orderings seem to consider it -insignificant, thus producing the ordering "event.c" "eventgenerator.c" -"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we -would like to treat numbers intelligently so that "file1" "file10" "file5" -is sorted as "file1" "file5" "file10". - -Note that this function depends on the [current locale][setlocale]. - - - a newly allocated string. This string should - be freed with g_free() when you are done with it. - - - - - a UTF-8 encoded string. - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - - - Finds the start of the next UTF-8 character in the string after @p. - -@p does not have to be at the beginning of a UTF-8 character. No check -is made to see if the character found is actually valid other than -it starts with an appropriate byte. - -If @end is %NULL, the return value will never be %NULL: if the end of the -string is reached, a pointer to the terminating nul byte is returned. If -@end is non-%NULL, the return value will be %NULL if the end of the string -is reached. - - - a pointer to the found character or %NULL if @end is - set and is reached - - - - - a pointer to a position within a UTF-8 encoded string - - - - a pointer to the byte following the end of the string, - or %NULL to indicate that the string is nul-terminated - - - - - - Given a position @p with a UTF-8 encoded string @str, find the start -of the previous UTF-8 character starting before @p. Returns %NULL if no -UTF-8 characters are present in @str before @p. - -@p does not have to be at the beginning of a UTF-8 character. No check -is made to see if the character found is actually valid other than -it starts with an appropriate byte. - - - a pointer to the found character or %NULL. - - - - - pointer to the beginning of a UTF-8 encoded string - - - - pointer to some position within @str - - - - - - Converts a sequence of bytes encoded as UTF-8 to a Unicode character. - -If @p does not point to a valid UTF-8 encoded character, results -are undefined. If you are not sure that the bytes are complete -valid Unicode characters, you should use g_utf8_get_char_validated() -instead. - - - the resulting character - - - - - a pointer to Unicode character encoded as UTF-8 - - - - - - Convert a sequence of bytes encoded as UTF-8 to a Unicode character. -This function checks for incomplete characters, for invalid characters -such as characters that are out of the range of Unicode, and for -overlong encodings of valid characters. - -Note that g_utf8_get_char_validated() returns (gunichar)-2 if -@max_len is positive and any of the bytes in the first UTF-8 character -sequence are nul. - - - the resulting character. If @p points to a partial - sequence at the end of a string that could begin a valid - character (or if @max_len is zero), returns (gunichar)-2; - otherwise, if @p does not point to a valid UTF-8 encoded - Unicode character, returns (gunichar)-1. - - - - - a pointer to Unicode character encoded as UTF-8 - - - - the maximum number of bytes to read, or -1 if @p is nul-terminated - - - - - - If the provided string is valid UTF-8, return a copy of it. If not, -return a copy in which bytes that could not be interpreted as valid Unicode -are replaced with the Unicode replacement character (U+FFFD). - -For example, this is an appropriate function to use if you have received -a string that was incorrectly declared to be UTF-8, and you need a valid -UTF-8 version of it that can be logged or displayed to the user, with the -assumption that it is close enough to ASCII or UTF-8 to be mostly -readable as-is. - - - a valid UTF-8 string whose content resembles @str - - - - - string to coerce into UTF-8 - - - - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. - - - - - - Skips to the next character in a UTF-8 string. The string must be -valid; this macro is as fast as possible, and has no error-checking. -You would use this macro to iterate over a string character by -character. The macro returns the start of the next UTF-8 character. -Before using this macro, use g_utf8_validate() to validate strings -that may contain invalid UTF-8. - - - - Pointer to the start of a valid UTF-8 character - - - - - Converts a string into canonical form, standardizing -such issues as whether a character with an accent -is represented as a base character and combining -accent or as a single precomposed character. The -string has to be valid UTF-8, otherwise %NULL is -returned. You should generally call g_utf8_normalize() -before comparing two Unicode strings. - -The normalization mode %G_NORMALIZE_DEFAULT only -standardizes differences that do not affect the -text content, such as the above-mentioned accent -representation. %G_NORMALIZE_ALL also standardizes -the "compatibility" characters in Unicode, such -as SUPERSCRIPT THREE to the standard forms -(in this case DIGIT THREE). Formatting information -may be lost but for most text operations such -characters should be considered the same. - -%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE -are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL, -but returned a result with composed forms rather -than a maximally decomposed form. This is often -useful if you intend to convert the string to -a legacy encoding or pass it to a system with -less capable Unicode handling. - - - a newly allocated string, that - is the normalized form of @str, or %NULL if @str - is not valid UTF-8. - - - - - a UTF-8 encoded string. - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - the type of normalization to perform. - - - - - - Converts from an integer character offset to a pointer to a position -within the string. - -Since 2.10, this function allows to pass a negative @offset to -step backwards. It is usually worth stepping backwards from the end -instead of forwards if @offset is in the last fourth of the string, -since moving forward is about 3 times faster than moving backward. - -Note that this function doesn't abort when reaching the end of @str. -Therefore you should be sure that @offset is within string boundaries -before calling that function. Call g_utf8_strlen() when unsure. -This limitation exists as this function is called frequently during -text rendering and therefore has to be as fast as possible. - - - the resulting pointer - - - - - a UTF-8 encoded string - - - - a character offset within @str - - - - - - Converts from a pointer to position within a string to an integer -character offset. - -Since 2.10, this function allows @pos to be before @str, and returns -a negative offset in this case. - - - the resulting character offset - - - - - a UTF-8 encoded string - - - - a pointer to a position within @str - - - - - - Finds the previous UTF-8 character in the string before @p. - -@p does not have to be at the beginning of a UTF-8 character. No check -is made to see if the character found is actually valid other than -it starts with an appropriate byte. If @p might be the first -character of the string, you must use g_utf8_find_prev_char() instead. - - - a pointer to the found character - - - - - a pointer to a position within a UTF-8 encoded string - - - - - - Finds the leftmost occurrence of the given Unicode character -in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. - - - %NULL if the string does not contain the character, - otherwise, a pointer to the start of the leftmost occurrence - of the character in the string. - - - - - a nul-terminated UTF-8 encoded string - - - - the maximum length of @p - - - - a Unicode character - - - - - - Converts all Unicode characters in the string that have a case -to lowercase. The exact manner that this is done depends -on the current locale, and may result in the number of -characters in the string changing. - - - a newly allocated string, with all characters - converted to lowercase. - - - - - a UTF-8 encoded string - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - - - Computes the length of the string in characters, not including -the terminating nul character. If the @max'th byte falls in the -middle of a character, the last (partial) character is not counted. - - - the length of the string in characters - - - - - pointer to the start of a UTF-8 encoded string - - - - the maximum number of bytes to examine. If @max - is less than 0, then the string is assumed to be - nul-terminated. If @max is 0, @p will not be examined and - may be %NULL. If @max is greater than 0, up to @max - bytes are examined - - - - - - Like the standard C strncpy() function, but copies a given number -of characters instead of a given number of bytes. The @src string -must be valid UTF-8 encoded text. (Use g_utf8_validate() on all -text before trying to use UTF-8 utility functions with it.) - -Note you must ensure @dest is at least 4 * @n to fit the -largest possible UTF-8 characters - - - @dest - - - - - buffer to fill with characters from @src - - - - UTF-8 encoded string - - - - character count - - - - - - Find the rightmost occurrence of the given Unicode character -in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. - - - %NULL if the string does not contain the character, - otherwise, a pointer to the start of the rightmost occurrence - of the character in the string. - - - - - a nul-terminated UTF-8 encoded string - - - - the maximum length of @p - - - - a Unicode character - - - - - - Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. -(Use g_utf8_validate() on all text before trying to use UTF-8 -utility functions with it.) - -This function is intended for programmatic uses of reversed strings. -It pays no attention to decomposed characters, combining marks, byte -order marks, directional indicators (LRM, LRO, etc) and similar -characters which might need special handling when reversing a string -for display purposes. - -Note that unlike g_strreverse(), this function returns -newly-allocated memory, which should be freed with g_free() when -no longer needed. - - - a newly-allocated string which is the reverse of @str - - - - - a UTF-8 encoded string - - - - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. - - - - - - Converts all Unicode characters in the string that have a case -to uppercase. The exact manner that this is done depends -on the current locale, and may result in the number of -characters in the string increasing. (For instance, the -German ess-zet will be changed to SS.) - - - a newly allocated string, with all characters - converted to uppercase. - - - - - a UTF-8 encoded string - - - - length of @str, in bytes, or -1 if @str is nul-terminated. - - - - - - Copies a substring out of a UTF-8 encoded string. -The substring will contain @end_pos - @start_pos characters. - - - a newly allocated copy of the requested - substring. Free with g_free() when no longer needed. - - - - - a UTF-8 encoded string - - - - a character offset within @str - - - - another character offset within @str - - - - - - Convert a string from UTF-8 to a 32-bit fixed width -representation as UCS-4. A trailing 0 character will be added to the -string after the converted text. - - - a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. - - - - - a UTF-8 encoded string - - - - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. - - - - location to store number of - bytes read, or %NULL. - If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - returned in case @str contains a trailing partial - character. If an error occurs then the index of the - invalid input is stored here. - - - - location to store number - of characters written or %NULL. The value here stored does not include - the trailing 0 character. - - - - - - Convert a string from UTF-8 to a 32-bit fixed width -representation as UCS-4, assuming valid UTF-8 input. -This function is roughly twice as fast as g_utf8_to_ucs4() -but does no error checking on the input. A trailing 0 character -will be added to the string after the converted text. - - - a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). - - - - - a UTF-8 encoded string - - - - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. - - - - location to store the - number of characters in the result, or %NULL. - - - - - - Convert a string from UTF-8 to UTF-16. A 0 character will be -added to the result after the converted text. - - - a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. - - - - - a UTF-8 encoded string - - - - the maximum length (number of bytes) of @str to use. - If @len < 0, then the string is nul-terminated. - - - - location to store number of - bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. - - - - location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. - - - - - - Validates UTF-8 encoded text. @str is the text to validate; -if @str is nul-terminated, then @max_len can be -1, otherwise -@max_len should be the number of bytes to validate. -If @end is non-%NULL, then the end of the valid range -will be stored there (i.e. the start of the first invalid -character if some bytes were invalid, or the end of the text -being validated otherwise). - -Note that g_utf8_validate() returns %FALSE if @max_len is -positive and any of the @max_len bytes are nul. - -Returns %TRUE if all of @str was valid. Many GLib and GTK+ -routines require valid UTF-8 as input; so data read from a file -or the network should be checked with g_utf8_validate() before -doing anything else with it. - - - %TRUE if the text was valid UTF-8 - - - - - a pointer to character data - - - - - - max bytes to validate, or -1 to go until NUL - - - - return location for end of valid data - - - - - - Validates UTF-8 encoded text. - -As with g_utf8_validate(), but @max_len must be set, and hence this function -will always return %FALSE if any of the bytes of @str are nul. - - - %TRUE if the text was valid UTF-8 - - - - - a pointer to character data - - - - - - max bytes to validate - - - - return location for end of valid data - - - - - - Parses the string @str and verify if it is a UUID. - -The function accepts the following syntax: - -- simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`) - -Note that hyphens are required within the UUID string itself, -as per the aforementioned RFC. - - - %TRUE if @str is a valid UUID, %FALSE otherwise. - - - - - a string representing a UUID - - - - - - Generates a random UUID (RFC 4122 version 4) as a string. It has the same -randomness guarantees as #GRand, so must not be used for cryptographic -purposes such as key generation, nonces, salts or one-time pads. - - - A string that should be freed with g_free(). - - - - - - - - - - - Determines if a given string is a valid D-Bus object path. You -should ensure that a string is a valid D-Bus object path before -passing it to g_variant_new_object_path(). - -A valid object path starts with `/` followed by zero or more -sequences of characters separated by `/` characters. Each sequence -must contain only the characters `[A-Z][a-z][0-9]_`. No sequence -(including the one following the final `/` character) may be empty. - - - %TRUE if @string is a D-Bus object path - - - - - a normal C nul-terminated string - - - - - - Determines if a given string is a valid D-Bus type signature. You -should ensure that a string is a valid D-Bus type signature before -passing it to g_variant_new_signature(). - -D-Bus type signatures consist of zero or more definite #GVariantType -strings in sequence. - - - %TRUE if @string is a D-Bus type signature - - - - - a normal C nul-terminated string - - - - - - Parses a #GVariant from a text representation. - -A single #GVariant is parsed from the content of @text. - -The format is described [here][gvariant-text]. - -The memory at @limit will never be accessed and the parser behaves as -if the character at @limit is the nul terminator. This has the -effect of bounding @text. - -If @endptr is non-%NULL then @text is permitted to contain data -following the value that this function parses and @endptr will be -updated to point to the first character past the end of the text -parsed by this function. If @endptr is %NULL and there is extra data -then an error is returned. - -If @type is non-%NULL then the value will be parsed to have that -type. This may result in additional parse errors (in the case that -the parsed value doesn't fit the type) but may also result in fewer -errors (in the case that the type would have been ambiguous, such as -with empty arrays). - -In the event that the parsing is successful, the resulting #GVariant -is returned. It is never floating, and must be freed with -g_variant_unref(). - -In case of any error, %NULL will be returned. If @error is non-%NULL -then it will be set to reflect the error that occurred. - -Officially, the language understood by the parser is "any string -produced by g_variant_print()". - -There may be implementation specific restrictions on deeply nested values, -which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is -guaranteed to handle nesting up to at least 64 levels. - - - a non-floating reference to a #GVariant, or %NULL - - - - - a #GVariantType, or %NULL - - - - a string containing a GVariant in text form - - - - a pointer to the end of @text, or %NULL - - - - a location to store the end pointer, or %NULL - - - - - - Pretty-prints a message showing the context of a #GVariant parse -error within the string for which parsing was attempted. - -The resulting string is suitable for output to the console or other -monospace media where newlines are treated in the usual way. - -The message will typically look something like one of the following: - -|[ -unterminated string constant: - (1, 2, 3, 'abc - ^^^^ -]| - -or - -|[ -unable to find a common type: - [1, 2, 3, 'str'] - ^ ^^^^^ -]| - -The format of the message may change in a future version. - -@error must have come from a failed attempt to g_variant_parse() and -@source_str must be exactly the same string that caused the error. -If @source_str was not nul-terminated when you passed it to -g_variant_parse() then you must add nul termination before using this -function. - - - the printed message - - - - - a #GError from the #GVariantParseError domain - - - - the string that was given to the parser - - - - - - - - - - - Same as g_variant_error_quark(). - Use g_variant_parse_error_quark() instead. - - - - - - - - - - - - - - - - - - - - - - - - - - - - Checks if @type_string is a valid GVariant type string. This call is -equivalent to calling g_variant_type_string_scan() and confirming -that the following character is a nul terminator. - - - %TRUE if @type_string is exactly one valid type string - -Since 2.24 - - - - - a pointer to any string - - - - - - Scan for a single complete and valid GVariant type string in @string. -The memory pointed to by @limit (or bytes beyond it) is never -accessed. - -If a valid type string is found, @endptr is updated to point to the -first character past the end of the string that was found and %TRUE -is returned. - -If there is no valid type string starting at @string, or if the type -string does not end before @limit then %FALSE is returned. - -For the simple case of checking if a string is a valid type string, -see g_variant_type_string_is_valid(). - - - %TRUE if a valid type string was found - - - - - a pointer to any string - - - - the end of @string, or %NULL - - - - location to store the end pointer, or %NULL - - - - - - An implementation of the GNU vasprintf() function which supports -positional parameters, as specified in the Single Unix Specification. -This function is similar to g_vsprintf(), except that it allocates a -string to hold the output, instead of putting the output in a buffer -you allocate in advance. - -The returned value in @string is guaranteed to be non-NULL, unless -@format contains `%lc` or `%ls` conversions, which can fail if no -multibyte representation is available for the given character. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - the return location for the newly-allocated string. - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the list of arguments to insert in the output. - - - - - - An implementation of the standard fprintf() function which supports -positional parameters, as specified in the Single Unix Specification. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - the stream to write to. - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the list of arguments to insert in the output. - - - - - - An implementation of the standard vprintf() function which supports -positional parameters, as specified in the Single Unix Specification. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the list of arguments to insert in the output. - - - - - - A safer form of the standard vsprintf() function. The output is guaranteed -to not exceed @n characters (including the terminating nul character), so -it is easy to ensure that a buffer overflow cannot occur. - -See also g_strdup_vprintf(). - -In versions of GLib prior to 1.2.3, this function may return -1 if the -output was truncated, and the truncated string may not be nul-terminated. -In versions prior to 1.3.12, this function returns the length of the output -string. - -The return value of g_vsnprintf() conforms to the vsnprintf() function -as standardized in ISO C99. Note that this is different from traditional -vsnprintf(), which returns the length of the output string. - -The format string may contain positional parameters, as specified in -the Single Unix Specification. - - - the number of bytes which would be produced if the buffer - was large enough. - - - - - the buffer to hold the output. - - - - the maximum number of bytes to produce (including the - terminating nul character). - - - - a standard printf() format string, but notice - string precision pitfalls][string-precision] - - - - the list of arguments to insert in the output. - - - - - - An implementation of the standard vsprintf() function which supports -positional parameters, as specified in the Single Unix Specification. - -`glib/gprintf.h` must be explicitly included in order to use this function. - - - the number of bytes printed. - - - - - the buffer to hold the output. - - - - a standard printf() format string, but notice - [string precision pitfalls][string-precision] - - - - the list of arguments to insert in the output. - - - - - - Logs a warning if the expression is not true. - - - - the expression to check - - - - - Internal function used to print messages from the public g_warn_if_reached() -and g_warn_if_fail() macros. - - - - - - - log domain - - - - file containing the warning - - - - line number of the warning - - - - function containing the warning - - - - expression which failed - - - - - - diff --git a/gir-files/GModule-2.0.gir b/gir-files/GModule-2.0.gir deleted file mode 100644 index a873bc978..000000000 --- a/gir-files/GModule-2.0.gir +++ /dev/null @@ -1,266 +0,0 @@ - - - - - - - - - The #GModule struct is an opaque data structure to represent a -[dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. -It should only be accessed via the following functions. - - - Closes a module. - - - %TRUE on success - - - - - a #GModule to close - - - - - - Ensures that a module will never be unloaded. -Any future g_module_close() calls on the module will be ignored. - - - - - - - a #GModule to make permanently resident - - - - - - Returns the filename that the module was opened with. - -If @module refers to the application itself, "main" is returned. - - - the filename of the module - - - - - a #GModule - - - - - - Gets a symbol pointer from a module, such as one exported -by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL. - - - %TRUE on success - - - - - a #GModule - - - - the name of the symbol to find - - - - returns the pointer to the symbol value - - - - - - A portable way to build the filename of a module. The platform-specific -prefix and suffix are added to the filename, if needed, and the result -is added to the directory, using the correct separator character. - -The directory should specify the directory where the module can be found. -It can be %NULL or an empty string to indicate that the module is in a -standard platform-specific directory, though this is not recommended -since the wrong module may be found. - -For example, calling g_module_build_path() on a Linux system with a -@directory of `/lib` and a @module_name of "mylibrary" will return -`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the -directory it will return `\Windows\mylibrary.dll`. - - - the complete path of the module, including the standard library - prefix and suffix. This should be freed when no longer needed - - - - - the directory where the module is. This can be - %NULL or the empty string to indicate that the standard platform-specific - directories will be used, though that is not recommended - - - - the name of the module - - - - - - Gets a string describing the last module error. - - - a string describing the last module error - - - - - Opens a module. If the module has already been opened, -its reference count is incremented. - -First of all g_module_open() tries to open @file_name as a module. -If that fails and @file_name has the ".la"-suffix (and is a libtool -archive) it tries to open the corresponding module. If that fails -and it doesn't have the proper module suffix for the platform -(#G_MODULE_SUFFIX), this suffix will be appended and the corresponding -module will be opened. If that fails and @file_name doesn't have the -".la"-suffix, this suffix is appended and g_module_open() tries to open -the corresponding module. If eventually that fails as well, %NULL is -returned. - - - a #GModule on success, or %NULL on failure - - - - - the name of the file containing the module, or %NULL - to obtain a #GModule representing the main program itself - - - - the flags used for opening the module. This can be the - logical OR of any of the #GModuleFlags - - - - - - Checks if modules are supported on the current platform. - - - %TRUE if modules are supported - - - - - - Specifies the type of the module initialization function. -If a module contains a function named g_module_check_init() it is called -automatically when the module is loaded. It is passed the #GModule structure -and should return %NULL on success or a string describing the initialization -error. - - - %NULL on success, or a string describing the initialization error - - - - - the #GModule corresponding to the module which has just been loaded - - - - - - Flags passed to g_module_open(). -Note that these flags are not supported on all platforms. - - - specifies that symbols are only resolved when - needed. The default action is to bind all symbols when the module - is loaded. - - - specifies that symbols in the module should - not be added to the global name space. The default action on most - platforms is to place symbols in the module in the global name space, - which may cause conflicts with existing symbols. - - - mask for all flags. - - - - Specifies the type of the module function called when it is unloaded. -If a module contains a function named g_module_unload() it is called -automatically when the module is unloaded. -It is passed the #GModule structure. - - - - - - - the #GModule about to be unloaded - - - - - - A portable way to build the filename of a module. The platform-specific -prefix and suffix are added to the filename, if needed, and the result -is added to the directory, using the correct separator character. - -The directory should specify the directory where the module can be found. -It can be %NULL or an empty string to indicate that the module is in a -standard platform-specific directory, though this is not recommended -since the wrong module may be found. - -For example, calling g_module_build_path() on a Linux system with a -@directory of `/lib` and a @module_name of "mylibrary" will return -`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the -directory it will return `\Windows\mylibrary.dll`. - - - the complete path of the module, including the standard library - prefix and suffix. This should be freed when no longer needed - - - - - the directory where the module is. This can be - %NULL or the empty string to indicate that the standard platform-specific - directories will be used, though that is not recommended - - - - the name of the module - - - - - - Gets a string describing the last module error. - - - a string describing the last module error - - - - - Checks if modules are supported on the current platform. - - - %TRUE if modules are supported - - - - - diff --git a/gir-files/GObject-2.0.gir b/gir-files/GObject-2.0.gir deleted file mode 100644 index 8a729057f..000000000 --- a/gir-files/GObject-2.0.gir +++ /dev/null @@ -1,17463 +0,0 @@ - - - - - - - - - This is the signature of marshaller functions, required to marshall -arrays of parameter values to signal emissions into C language callback -invocations. It is merely an alias to #GClosureMarshal since the #GClosure -mechanism takes over responsibility of actual function invocation for the -signal system. - - - - - This is the signature of va_list marshaller functions, an optional -marshaller that can be used in some situations to avoid -marshalling the signal argument into GValues. - - - - - A numerical value which represents the unique identifier of a registered -type. - - - - - A convenience macro to ease adding private data to instances of a new type -in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or -G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). - -For instance: - -|[<!-- language="C" --> - typedef struct _MyObject MyObject; - typedef struct _MyObjectClass MyObjectClass; - - typedef struct { - gint foo; - gint bar; - } MyObjectPrivate; - - G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT, - G_ADD_PRIVATE (MyObject)) -]| - -Will add MyObjectPrivate as the private data to any instance of the MyObject -type. - -G_DEFINE_TYPE_* macros will automatically create a private function -based on the arguments to this macro, which can be used to safely -retrieve the private data from an instance of the type; for instance: - -|[<!-- language="C" --> - gint - my_object_get_foo (MyObject *obj) - { - MyObjectPrivate *priv = my_object_get_instance_private (obj); - - g_return_val_if_fail (MY_IS_OBJECT (obj), 0); - - return priv->foo; - } - - void - my_object_set_bar (MyObject *obj, - gint bar) - { - MyObjectPrivate *priv = my_object_get_instance_private (obj); - - g_return_if_fail (MY_IS_OBJECT (obj)); - - if (priv->bar != bar) - priv->bar = bar; - } -]| - -Note that this macro can only be used together with the G_DEFINE_TYPE_* -macros, since it depends on variable names from those macros. - -Also note that private structs added with these macros must have a struct -name of the form `TypeNamePrivate`. - -It is safe to call the `_get_instance_private` function on %NULL or invalid -objects since it's only adding an offset to the instance pointer. In that -case the returned pointer must not be dereferenced. - - - - the name of the type in CamelCase - - - - - A convenience macro to ease adding private data to instances of a new dynamic -type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See -G_ADD_PRIVATE() for details, it is similar but for static types. - -Note that this macro can only be used together with the -G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable -names from that macro. - - - - the name of the type in CamelCase - - - - - - - - - - - - A callback function used by the type system to finalize those portions -of a derived types class structure that were setup from the corresponding -GBaseInitFunc() function. Class finalization basically works the inverse -way in which class initialization is performed. -See GClassInitFunc() for a discussion of the class initialization process. - - - - - - - The #GTypeClass structure to finalize - - - - - - A callback function used by the type system to do base initialization -of the class structures of derived types. It is called as part of the -initialization process of all derived classes and should reallocate -or reset all dynamic class members copied over from the parent class. -For example, class members (such as strings) that are not sufficiently -handled by a plain memory copy of the parent class into the derived class -have to be altered. See GClassInitFunc() for a discussion of the class -initialization process. - - - - - - - The #GTypeClass structure to initialize - - - - - - #GBinding is the representation of a binding between a property on a -#GObject instance (or source) and another property on another #GObject -instance (or target). Whenever the source property changes, the same -value is applied to the target property; for instance, the following -binding: - -|[<!-- language="C" --> - g_object_bind_property (object1, "property-a", - object2, "property-b", - G_BINDING_DEFAULT); -]| - -will cause the property named "property-b" of @object2 to be updated -every time g_object_set() or the specific accessor changes the value of -the property "property-a" of @object1. - -It is possible to create a bidirectional binding between two properties -of two #GObject instances, so that if either property changes, the -other is updated as well, for instance: - -|[<!-- language="C" --> - g_object_bind_property (object1, "property-a", - object2, "property-b", - G_BINDING_BIDIRECTIONAL); -]| - -will keep the two properties in sync. - -It is also possible to set a custom transformation function (in both -directions, in case of a bidirectional binding) to apply a custom -transformation from the source value to the target value before -applying it; for instance, the following binding: - -|[<!-- language="C" --> - g_object_bind_property_full (adjustment1, "value", - adjustment2, "value", - G_BINDING_BIDIRECTIONAL, - celsius_to_fahrenheit, - fahrenheit_to_celsius, - NULL, NULL); -]| - -will keep the "value" property of the two adjustments in sync; the -@celsius_to_fahrenheit function will be called whenever the "value" -property of @adjustment1 changes and will transform the current value -of the property before applying it to the "value" property of @adjustment2. - -Vice versa, the @fahrenheit_to_celsius function will be called whenever -the "value" property of @adjustment2 changes, and will transform the -current value of the property before applying it to the "value" property -of @adjustment1. - -Note that #GBinding does not resolve cycles by itself; a cycle like - -|[ - object1:propertyA -> object2:propertyB - object2:propertyB -> object3:propertyC - object3:propertyC -> object1:propertyA -]| - -might lead to an infinite loop. The loop, in this particular case, -can be avoided if the objects emit the #GObject::notify signal only -if the value has effectively been changed. A binding is implemented -using the #GObject::notify signal, so it is susceptible to all the -various ways of blocking a signal emission, like g_signal_stop_emission() -or g_signal_handler_block(). - -A binding will be severed, and the resources it allocates freed, whenever -either one of the #GObject instances it refers to are finalized, or when -the #GBinding instance loses its last reference. - -Bindings for languages with garbage collection can use -g_binding_unbind() to explicitly release a binding between the source -and target properties, instead of relying on the last reference on the -binding, source, and target instances to drop. - -#GBinding is available since GObject 2.26 - - Retrieves the flags passed when constructing the #GBinding. - - - the #GBindingFlags used by the #GBinding - - - - - a #GBinding - - - - - - Retrieves the #GObject instance used as the source of the binding. - - - the source #GObject - - - - - a #GBinding - - - - - - Retrieves the name of the property of #GBinding:source used as the source -of the binding. - - - the name of the source property - - - - - a #GBinding - - - - - - Retrieves the #GObject instance used as the target of the binding. - - - the target #GObject - - - - - a #GBinding - - - - - - Retrieves the name of the property of #GBinding:target used as the target -of the binding. - - - the name of the target property - - - - - a #GBinding - - - - - - Explicitly releases the binding between the source and the target -property expressed by @binding. - -This function will release the reference that is being held on -the @binding instance; if you want to hold on to the #GBinding instance -after calling g_binding_unbind(), you will need to hold a reference -to it. - - - - - - - a #GBinding - - - - - - Flags to be used to control the #GBinding - - - - The #GObject that should be used as the source of the binding - - - - The name of the property of #GBinding:source that should be used -as the source of the binding. - -This should be in [canonical form][canonical-parameter-names] to get the -best performance. - - - - The #GObject that should be used as the target of the binding - - - - The name of the property of #GBinding:target that should be used -as the target of the binding. - -This should be in [canonical form][canonical-parameter-names] to get the -best performance. - - - - - Flags to be passed to g_object_bind_property() or -g_object_bind_property_full(). - -This enumeration can be extended at later date. - - The default binding; if the source property - changes, the target property is updated with its value. - - - Bidirectional binding; if either the - property of the source or the property of the target changes, - the other is updated. - - - Synchronize the values of the source and - target properties when creating the binding; the direction of - the synchronization is always from the source to the target. - - - If the two properties being bound are - booleans, setting one to %TRUE will result in the other being - set to %FALSE and vice versa. This flag will only work for - boolean properties, and cannot be used when passing custom - transformation functions to g_object_bind_property_full(). - - - - A function to be called to transform @from_value to @to_value. If -this is the @transform_to function of a binding, then @from_value -is the @source_property on the @source object, and @to_value is the -@target_property on the @target object. If this is the -@transform_from function of a %G_BINDING_BIDIRECTIONAL binding, -then those roles are reversed. - - - %TRUE if the transformation was successful, and %FALSE - otherwise - - - - - a #GBinding - - - - the #GValue containing the value to transform - - - - the #GValue in which to store the transformed value - - - - data passed to the transform function - - - - - - This function is provided by the user and should produce a copy -of the passed in boxed structure. - - - The newly created copy of the boxed structure. - - - - - The boxed structure to be copied. - - - - - - This function is provided by the user and should free the boxed -structure passed. - - - - - - - The boxed structure to be freed. - - - - - - Cast a function pointer to a #GCallback. - - - - a function pointer. - - - - - Checks whether the user data of the #GCClosure should be passed as the -first parameter to the callback. See g_cclosure_new_swap(). - - - - a #GCClosure - - - - - A #GCClosure is a specialization of #GClosure for C function callbacks. - - - the #GClosure - - - - the callback function - - - - A #GClosureMarshal function for use with signals with handlers that -take two boxed pointers as arguments and return a boolean. If you -have such a signal, you will probably also need to use an -accumulator, such as g_signal_accumulator_true_handled(). - - - - - - - A #GClosure. - - - - A #GValue to store the return value. May be %NULL - if the callback of closure doesn't return a value. - - - - The length of the @param_values array. - - - - An array of #GValues holding the arguments - on which to invoke the callback of closure. - - - - The invocation hint given as the last argument to - g_closure_invoke(). - - - - Additional data specified when registering the - marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue which can store the returned #gboolean - - - - 2 - - - - a #GValue array holding instance and arg1 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue, which can store the returned string - - - - 3 - - - - a #GValue array holding instance, arg1 and arg2 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gboolean parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GBoxed* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gchar parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gdouble parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the enumeration parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the flags parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gfloat parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gint parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #glong parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GObject* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GParamSpec* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gpointer parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gchar* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #guchar parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #guint parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 3 - - - - a #GValue array holding instance, arg1 and arg2 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gulong parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GVariant* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 1 - - - - a #GValue array holding only the instance - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - A generic marshaller function implemented via -[libffi](http://sourceware.org/libffi/). - -Normally this function is not passed explicitly to g_signal_new(), -but used automatically by GLib when specifying a %NULL marshaller. - - - - - - - A #GClosure. - - - - A #GValue to store the return value. May be %NULL - if the callback of closure doesn't return a value. - - - - The length of the @param_values array. - - - - An array of #GValues holding the arguments - on which to invoke the callback of closure. - - - - The invocation hint given as the last argument to - g_closure_invoke(). - - - - Additional data specified when registering the - marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - - - A generic #GVaClosureMarshal function implemented via -[libffi](http://sourceware.org/libffi/). - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is - invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args_list. - - - - - - - - Creates a new closure which invokes @callback_func with @user_data as -the last parameter. - -@destroy_data will be called as a finalize notifier on the #GClosure. - - - a floating reference to a new #GCClosure - - - - - the function to invoke - - - - user data to pass to @callback_func - - - - destroy notify to be called when @user_data is no longer used - - - - - - A variant of g_cclosure_new() which uses @object as @user_data and -calls g_object_watch_closure() on @object and the created -closure. This function is useful when you have a callback closely -associated with a #GObject, and want the callback to no longer run -after the object is is freed. - - - a new #GCClosure - - - - - the function to invoke - - - - a #GObject pointer to pass to @callback_func - - - - - - A variant of g_cclosure_new_swap() which uses @object as @user_data -and calls g_object_watch_closure() on @object and the created -closure. This function is useful when you have a callback closely -associated with a #GObject, and want the callback to no longer run -after the object is is freed. - - - a new #GCClosure - - - - - the function to invoke - - - - a #GObject pointer to pass to @callback_func - - - - - - Creates a new closure which invokes @callback_func with @user_data as -the first parameter. - -@destroy_data will be called as a finalize notifier on the #GClosure. - - - a floating reference to a new #GCClosure - - - - - the function to invoke - - - - user data to pass to @callback_func - - - - destroy notify to be called when @user_data is no longer used - - - - - - - Check if the closure still needs a marshaller. See g_closure_set_marshal(). - - - - a #GClosure - - - - - Get the total number of notifiers connected with the closure @cl. -The count includes the meta marshaller, the finalize and invalidate notifiers -and the marshal guards. Note that each guard counts as two notifiers. -See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), -g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). - - - - a #GClosure - - - - - The type used for callback functions in structure definitions and function -signatures. This doesn't mean that all callback functions must take no -parameters and return void. The required signature of a callback function -is determined by the context in which is used (e.g. the signal to which it -is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. - - - - - - - A callback function used by the type system to finalize a class. -This function is rarely needed, as dynamically allocated class resources -should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). -Also, specification of a GClassFinalizeFunc() in the #GTypeInfo -structure of a static type is invalid, because classes of static types -will never be finalized (they are artificially kept alive when their -reference count drops to zero). - - - - - - - The #GTypeClass structure to finalize - - - - The @class_data member supplied via the #GTypeInfo structure - - - - - - A callback function used by the type system to initialize the class -of a specific type. This function should initialize all static class -members. - -The initialization process of a class involves: - -- Copying common members from the parent class over to the - derived class structure. -- Zero initialization of the remaining members not copied - over from the parent class. -- Invocation of the GBaseInitFunc() initializers of all parent - types and the class' type. -- Invocation of the class' GClassInitFunc() initializer. - -Since derived classes are partially initialized through a memory copy -of the parent class, the general rule is that GBaseInitFunc() and -GBaseFinalizeFunc() should take care of necessary reinitialization -and release of those class members that were introduced by the type -that specified these GBaseInitFunc()/GBaseFinalizeFunc(). -GClassInitFunc() should only care about initializing static -class members, while dynamic class members (such as allocated strings -or reference counted resources) are better handled by a GBaseInitFunc() -for this type, so proper initialization of the dynamic class members -is performed for class initialization of derived types as well. - -An example may help to correspond the intend of the different class -initializers: - -|[<!-- language="C" --> -typedef struct { - GObjectClass parent_class; - gint static_integer; - gchar *dynamic_string; -} TypeAClass; -static void -type_a_base_class_init (TypeAClass *class) -{ - class->dynamic_string = g_strdup ("some string"); -} -static void -type_a_base_class_finalize (TypeAClass *class) -{ - g_free (class->dynamic_string); -} -static void -type_a_class_init (TypeAClass *class) -{ - class->static_integer = 42; -} - -typedef struct { - TypeAClass parent_class; - gfloat static_float; - GString *dynamic_gstring; -} TypeBClass; -static void -type_b_base_class_init (TypeBClass *class) -{ - class->dynamic_gstring = g_string_new ("some other string"); -} -static void -type_b_base_class_finalize (TypeBClass *class) -{ - g_string_free (class->dynamic_gstring); -} -static void -type_b_class_init (TypeBClass *class) -{ - class->static_float = 3.14159265358979323846; -} -]| -Initialization of TypeBClass will first cause initialization of -TypeAClass (derived classes reference their parent classes, see -g_type_class_ref() on this). - -Initialization of TypeAClass roughly involves zero-initializing its fields, -then calling its GBaseInitFunc() type_a_base_class_init() to allocate -its dynamic members (dynamic_string), and finally calling its GClassInitFunc() -type_a_class_init() to initialize its static members (static_integer). -The first step in the initialization process of TypeBClass is then -a plain memory copy of the contents of TypeAClass into TypeBClass and -zero-initialization of the remaining fields in TypeBClass. -The dynamic members of TypeAClass within TypeBClass now need -reinitialization which is performed by calling type_a_base_class_init() -with an argument of TypeBClass. - -After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() -is called to allocate the dynamic members of TypeBClass (dynamic_gstring), -and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), -is called to complete the initialization process with the static members -(static_float). - -Corresponding finalization counter parts to the GBaseInitFunc() functions -have to be provided to release allocated resources at class finalization -time. - - - - - - - The #GTypeClass structure to initialize. - - - - The @class_data member supplied via the #GTypeInfo structure. - - - - - - A #GClosure represents a callback supplied by the programmer. It -will generally comprise a function of some kind and a marshaller -used to call it. It is the responsibility of the marshaller to -convert the arguments for the invocation from #GValues into -a suitable form, perform the callback on the converted arguments, -and transform the return value back into a #GValue. - -In the case of C programs, a closure usually just holds a pointer -to a function and maybe a data argument, and the marshaller -converts between #GValue and native C types. The GObject -library provides the #GCClosure type for this purpose. Bindings for -other languages need marshallers which convert between #GValues -and suitable representations in the runtime of the language in -order to use functions written in that language as callbacks. Use -g_closure_set_marshal() to set the marshaller on such a custom -closure implementation. - -Within GObject, closures play an important role in the -implementation of signals. When a signal is registered, the -@c_marshaller argument to g_signal_new() specifies the default C -marshaller for any closure which is connected to this -signal. GObject provides a number of C marshallers for this -purpose, see the g_cclosure_marshal_*() functions. Additional C -marshallers can be generated with the [glib-genmarshal][glib-genmarshal] -utility. Closures can be explicitly connected to signals with -g_signal_connect_closure(), but it usually more convenient to let -GObject create a closure automatically by using one of the -g_signal_connect_*() functions which take a callback function/user -data pair. - -Using closures has a number of important advantages over a simple -callback function/data pointer combination: - -- Closures allow the callee to get the types of the callback parameters, - which means that language bindings don't have to write individual glue - for each callback type. - -- The reference counting of #GClosure makes it easy to handle reentrancy - right; if a callback is removed while it is being invoked, the closure - and its parameters won't be freed until the invocation finishes. - -- g_closure_invalidate() and invalidation notifiers allow callbacks to be - automatically removed when the objects they point to go away. - - - - - - - - - - - - - - - - - - - - - - - - - - - Indicates whether the closure is currently being invoked with - g_closure_invoke() - - - - Indicates whether the closure has been invalidated by - g_closure_invalidate() - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A variant of g_closure_new_simple() which stores @object in the -@data field of the closure and calls g_object_watch_closure() on -@object and the created closure. This function is mainly useful -when implementing new types of closures. - - - a newly allocated #GClosure - - - - - the size of the structure to allocate, must be at least - `sizeof (GClosure)` - - - - a #GObject pointer to store in the @data field of the newly - allocated #GClosure - - - - - - Allocates a struct of the given size and initializes the initial -part as a #GClosure. This function is mainly useful when -implementing new types of closures. - -|[<!-- language="C" --> -typedef struct _MyClosure MyClosure; -struct _MyClosure -{ - GClosure closure; - // extra data goes here -}; - -static void -my_closure_finalize (gpointer notify_data, - GClosure *closure) -{ - MyClosure *my_closure = (MyClosure *)closure; - - // free extra data here -} - -MyClosure *my_closure_new (gpointer data) -{ - GClosure *closure; - MyClosure *my_closure; - - closure = g_closure_new_simple (sizeof (MyClosure), data); - my_closure = (MyClosure *) closure; - - // initialize extra data here - - g_closure_add_finalize_notifier (closure, notify_data, - my_closure_finalize); - return my_closure; -} -]| - - - a floating reference to a new #GClosure - - - - - the size of the structure to allocate, must be at least - `sizeof (GClosure)` - - - - data to store in the @data field of the newly allocated #GClosure - - - - - - Registers a finalization notifier which will be called when the -reference count of @closure goes down to 0. Multiple finalization -notifiers on a single closure are invoked in unspecified order. If -a single call to g_closure_unref() results in the closure being -both invalidated and finalized, then the invalidate notifiers will -be run before the finalize notifiers. - - - - - - - a #GClosure - - - - data to pass to @notify_func - - - - the callback function to register - - - - - - Registers an invalidation notifier which will be called when the -@closure is invalidated with g_closure_invalidate(). Invalidation -notifiers are invoked before finalization notifiers, in an -unspecified order. - - - - - - - a #GClosure - - - - data to pass to @notify_func - - - - the callback function to register - - - - - - Adds a pair of notifiers which get invoked before and after the -closure callback, respectively. This is typically used to protect -the extra arguments for the duration of the callback. See -g_object_watch_closure() for an example of marshal guards. - - - - - - - a #GClosure - - - - data to pass - to @pre_marshal_notify - - - - a function to call before the closure callback - - - - data to pass - to @post_marshal_notify - - - - a function to call after the closure callback - - - - - - Sets a flag on the closure to indicate that its calling -environment has become invalid, and thus causes any future -invocations of g_closure_invoke() on this @closure to be -ignored. Also, invalidation notifiers installed on the closure will -be called at this point. Note that unless you are holding a -reference to the closure yourself, the invalidation notifiers may -unref the closure and cause it to be destroyed, so if you need to -access the closure after calling g_closure_invalidate(), make sure -that you've previously called g_closure_ref(). - -Note that g_closure_invalidate() will also be called when the -reference count of a closure drops to zero (unless it has already -been invalidated before). - - - - - - - #GClosure to invalidate - - - - - - Invokes the closure, i.e. executes the callback represented by the @closure. - - - - - - - a #GClosure - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure - doesn't return a value. - - - - the length of the @param_values array - - - - an array of - #GValues holding the arguments on which to - invoke the callback of @closure - - - - - - a context-dependent invocation hint - - - - - - Increments the reference count on a closure to force it staying -alive while the caller holds a pointer to it. - - - The @closure passed in, for convenience - - - - - #GClosure to increment the reference count on - - - - - - Removes a finalization notifier. - -Notice that notifiers are automatically removed after they are run. - - - - - - - a #GClosure - - - - data which was passed to g_closure_add_finalize_notifier() - when registering @notify_func - - - - the callback function to remove - - - - - - Removes an invalidation notifier. - -Notice that notifiers are automatically removed after they are run. - - - - - - - a #GClosure - - - - data which was passed to g_closure_add_invalidate_notifier() - when registering @notify_func - - - - the callback function to remove - - - - - - Sets the marshaller of @closure. The `marshal_data` -of @marshal provides a way for a meta marshaller to provide additional -information to the marshaller. (See g_closure_set_meta_marshal().) For -GObject's C predefined marshallers (the g_cclosure_marshal_*() -functions), what it provides is a callback function to use instead of -@closure->callback. - - - - - - - a #GClosure - - - - a #GClosureMarshal function - - - - - - Sets the meta marshaller of @closure. A meta marshaller wraps -@closure->marshal and modifies the way it is called in some -fashion. The most common use of this facility is for C callbacks. -The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), -are used everywhere, but the way that we get the callback function -differs. In most cases we want to use @closure->callback, but in -other cases we want to use some different technique to retrieve the -callback function. - -For example, class closures for signals (see -g_signal_type_cclosure_new()) retrieve the callback function from a -fixed offset in the class structure. The meta marshaller retrieves -the right callback and passes it to the marshaller as the -@marshal_data argument. - - - - - - - a #GClosure - - - - context-dependent data to pass - to @meta_marshal - - - - a #GClosureMarshal function - - - - - - Takes over the initial ownership of a closure. Each closure is -initially created in a "floating" state, which means that the initial -reference count is not owned by any caller. g_closure_sink() checks -to see if the object is still floating, and if so, unsets the -floating state and decreases the reference count. If the closure -is not floating, g_closure_sink() does nothing. The reason for the -existence of the floating state is to prevent cumbersome code -sequences like: -|[<!-- language="C" --> -closure = g_cclosure_new (cb_func, cb_data); -g_source_set_closure (source, closure); -g_closure_unref (closure); // GObject doesn't really need this -]| -Because g_source_set_closure() (and similar functions) take ownership of the -initial reference count, if it is unowned, we instead can write: -|[<!-- language="C" --> -g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); -]| - -Generally, this function is used together with g_closure_ref(). Ane example -of storing a closure for later notification looks like: -|[<!-- language="C" --> -static GClosure *notify_closure = NULL; -void -foo_notify_set_closure (GClosure *closure) -{ - if (notify_closure) - g_closure_unref (notify_closure); - notify_closure = closure; - if (notify_closure) - { - g_closure_ref (notify_closure); - g_closure_sink (notify_closure); - } -} -]| - -Because g_closure_sink() may decrement the reference count of a closure -(if it hasn't been called on @closure yet) just like g_closure_unref(), -g_closure_ref() should be called prior to this function. - - - - - - - #GClosure to decrement the initial reference count on, if it's - still being held - - - - - - Decrements the reference count of a closure after it was previously -incremented by the same caller. If no other callers are using the -closure, then the closure will be destroyed and freed. - - - - - - - #GClosure to decrement the reference count on - - - - - - - The type used for marshaller functions. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the length of the @param_values array - - - - an array of - #GValues holding the arguments on which to invoke the - callback of @closure - - - - - - the invocation hint given as the - last argument to g_closure_invoke() - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - - - The type used for the various notification callbacks which can be registered -on closures. - - - - - - - data specified when registering the notification callback - - - - the #GClosure on which the notification is emitted - - - - - - - - - - - - - - - The connection flags are used to specify the behaviour of a signal's -connection. - - - whether the handler should be called before or after the - default handler of the signal. - - - whether the instance and data should be swapped when - calling the handler; see g_signal_connect_swapped() for an example. - - - - A convenience macro for emitting the usual declarations in the -header file for a type which is intended to be subclassed. - -You might use it in a header as follows: - -|[ -#ifndef _gtk_frobber_h_ -#define _gtk_frobber_h_ - -#define GTK_TYPE_FROBBER gtk_frobber_get_type () -GDK_AVAILABLE_IN_3_12 -G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget) - -struct _GtkFrobberClass -{ - GtkWidgetClass parent_class; - - void (* handle_frob) (GtkFrobber *frobber, - guint n_frobs); - - gpointer padding[12]; -}; - -GtkWidget * gtk_frobber_new (void); - -... - -#endif -]| - -This results in the following things happening: - -- the usual gtk_frobber_get_type() function is declared with a return type of #GType - -- the GtkFrobber struct is created with GtkWidget as the first and only item. You are expected to use - a private structure from your .c file to store your instance variables. - -- the GtkFrobberClass type is defined as a typedef to struct _GtkFrobberClass, which is left undefined. - You should do this from the header file directly after you use the macro. - -- the GTK_FROBBER() and GTK_FROBBER_CLASS() casts are emitted as static inline functions along with - the GTK_IS_FROBBER() and GTK_IS_FROBBER_CLASS() type checking functions and GTK_FROBBER_GET_CLASS() - function. - -- g_autoptr() support being added for your type, based on the type of your parent class - -You can only use this function if your parent type also supports g_autoptr(). - -Because the type macro (GTK_TYPE_FROBBER in the above example) is not a callable, you must continue to -manually define this as a macro for yourself. - -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro -to be used in the usual way with export control and API versioning macros. - -If you are writing a library, it is important to note that it is possible to convert a type from using -G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you -should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be -subclassed. Once a class structure has been exposed it is not possible to change its size or remove or -reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use -G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance -structures, use G_DECLARE_FINAL_TYPE(). - -If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your -class structure to leave space for the addition of future virtual functions. - - - - The name of the new type, in camel case (like GtkWidget) - - - The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') - - - The name of the module, in all caps (like 'GTK') - - - The bare name of the type, in all caps (like 'WIDGET') - - - the name of the parent type, in camel case (like GtkWidget) - - - - - A convenience macro for emitting the usual declarations in the header file for a type which is not (at the -present time) intended to be subclassed. - -You might use it in a header as follows: - -|[ -#ifndef _myapp_window_h_ -#define _myapp_window_h_ - -#include <gtk/gtk.h> - -#define MY_APP_TYPE_WINDOW my_app_window_get_type () -G_DECLARE_FINAL_TYPE (MyAppWindow, my_app_window, MY_APP, WINDOW, GtkWindow) - -MyAppWindow * my_app_window_new (void); - -... - -#endif -]| - -This results in the following things happening: - -- the usual my_app_window_get_type() function is declared with a return type of #GType - -- the MyAppWindow types is defined as a typedef of struct _MyAppWindow. The struct itself is not - defined and should be defined from the .c file before G_DEFINE_TYPE() is used. - -- the MY_APP_WINDOW() cast is emitted as static inline function along with the MY_APP_IS_WINDOW() type - checking function - -- the MyAppWindowClass type is defined as a struct containing GtkWindowClass. This is done for the - convenience of the person defining the type and should not be considered to be part of the ABI. In - particular, without a firm declaration of the instance structure, it is not possible to subclass the type - and therefore the fact that the size of the class structure is exposed is not a concern and it can be - freely changed at any point in the future. - -- g_autoptr() support being added for your type, based on the type of your parent class - -You can only use this function if your parent type also supports g_autoptr(). - -Because the type macro (MY_APP_TYPE_WINDOW in the above example) is not a callable, you must continue to -manually define this as a macro for yourself. - -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro -to be used in the usual way with export control and API versioning macros. - -If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). - -If you are writing a library, it is important to note that it is possible to convert a type from using -G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you -should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be -subclassed. Once a class structure has been exposed it is not possible to change its size or remove or -reorder items without breaking the API and/or ABI. - - - - The name of the new type, in camel case (like GtkWidget) - - - The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') - - - The name of the module, in all caps (like 'GTK') - - - The bare name of the type, in all caps (like 'WIDGET') - - - the name of the parent type, in camel case (like GtkWidget) - - - - - A convenience macro for emitting the usual declarations in the header file for a GInterface type. - -You might use it in a header as follows: - -|[ -#ifndef _my_model_h_ -#define _my_model_h_ - -#define MY_TYPE_MODEL my_model_get_type () -GDK_AVAILABLE_IN_3_12 -G_DECLARE_INTERFACE (MyModel, my_model, MY, MODEL, GObject) - -struct _MyModelInterface -{ - GTypeInterface g_iface; - - gpointer (* get_item) (MyModel *model); -}; - -gpointer my_model_get_item (MyModel *model); - -... - -#endif -]| - -This results in the following things happening: - -- the usual my_model_get_type() function is declared with a return type of #GType - -- the MyModelInterface type is defined as a typedef to struct _MyModelInterface, - which is left undefined. You should do this from the header file directly after - you use the macro. - -- the MY_MODEL() cast is emitted as static inline functions along with - the MY_IS_MODEL() type checking function and MY_MODEL_GET_IFACE() function. - -- g_autoptr() support being added for your type, based on your prerequisite type. - -You can only use this function if your prerequisite type also supports g_autoptr(). - -Because the type macro (MY_TYPE_MODEL in the above example) is not a callable, you must continue to -manually define this as a macro for yourself. - -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro -to be used in the usual way with export control and API versioning macros. - - - - The name of the new type, in camel case (like GtkWidget) - - - The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') - - - The name of the module, in all caps (like 'GTK') - - - The bare name of the type, in all caps (like 'WIDGET') - - - the name of the prerequisite type, in camel case (like GtkWidget) - - - - - A convenience macro for type implementations. -Similar to G_DEFINE_TYPE(), but defines an abstract type. -See G_DEFINE_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - - - A convenience macro for type implementations. -Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and -allows you to insert custom code into the *_get_type() function, e.g. -interface implementations via G_IMPLEMENT_INTERFACE(). -See G_DEFINE_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - Custom code that gets inserted in the @type_name_get_type() function. - - - - - Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. -See G_DEFINE_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - - - A convenience macro for boxed type implementations, which defines a -type_name_get_type() function registering the boxed type. - - - - The name of the new type, in Camel case - - - The name of the new type, in lowercase, with words - separated by '_' - - - the #GBoxedCopyFunc for the new type - - - the #GBoxedFreeFunc for the new type - - - - - A convenience macro for boxed type implementations. -Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the -type_name_get_type() function, e.g. to register value transformations with -g_value_register_transform_func(), for instance: - -|[<!-- language="C" --> -G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle, - gdk_rectangle_copy, - gdk_rectangle_free, - register_rectangle_transform_funcs (g_define_type_id)) -]| - -Similarly to the %G_DEFINE_TYPE family of macros, the #GType of the newly -defined boxed type is exposed in the `g_define_type_id` variable. - - - - The name of the new type, in Camel case - - - The name of the new type, in lowercase, with words - separated by '_' - - - the #GBoxedCopyFunc for the new type - - - the #GBoxedFreeFunc for the new type - - - Custom code that gets inserted in the *_get_type() function - - - - - A convenience macro for dynamic type implementations, which declares a -class initialization function, an instance initialization function (see -#GTypeInfo for information about these) and a static variable named -`t_n`_parent_class pointing to the parent class. Furthermore, -it defines a `*_get_type()` and a static `*_register_type()` functions -for use in your `module_init()`. - -See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - - - A more general version of G_DEFINE_DYNAMIC_TYPE() which -allows to specify #GTypeFlags and custom code. - -|[ -G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, - gtk_gadget, - GTK_TYPE_THING, - 0, - G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, - gtk_gadget_gizmo_init)); -]| -expands to -|[ -static void gtk_gadget_init (GtkGadget *self); -static void gtk_gadget_class_init (GtkGadgetClass *klass); -static void gtk_gadget_class_finalize (GtkGadgetClass *klass); - -static gpointer gtk_gadget_parent_class = NULL; -static GType gtk_gadget_type_id = 0; - -static void gtk_gadget_class_intern_init (gpointer klass) -{ - gtk_gadget_parent_class = g_type_class_peek_parent (klass); - gtk_gadget_class_init ((GtkGadgetClass*) klass); -} - -GType -gtk_gadget_get_type (void) -{ - return gtk_gadget_type_id; -} - -static void -gtk_gadget_register_type (GTypeModule *type_module) -{ - const GTypeInfo g_define_type_info = { - sizeof (GtkGadgetClass), - (GBaseInitFunc) NULL, - (GBaseFinalizeFunc) NULL, - (GClassInitFunc) gtk_gadget_class_intern_init, - (GClassFinalizeFunc) gtk_gadget_class_finalize, - NULL, // class_data - sizeof (GtkGadget), - 0, // n_preallocs - (GInstanceInitFunc) gtk_gadget_init, - NULL // value_table - }; - gtk_gadget_type_id = g_type_module_register_type (type_module, - GTK_TYPE_THING, - "GtkGadget", - &g_define_type_info, - (GTypeFlags) flags); - { - const GInterfaceInfo g_implement_interface_info = { - (GInterfaceInitFunc) gtk_gadget_gizmo_init - }; - g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - } -} -]| - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - #GTypeFlags to pass to g_type_module_register_type() - - - Custom code that gets inserted in the *_get_type() function. - - - - - A convenience macro for #GTypeInterface definitions, which declares -a default vtable initialization function and defines a *_get_type() -function. - -The macro expects the interface initialization function to have the -name `t_n ## _default_init`, and the interface structure to have the -name `TN ## Interface`. - -The initialization function has signature -`static void t_n ## _default_init (TypeName##Interface *klass);`, rather than -the full #GInterfaceInitFunc signature, for brevity and convenience. If you -need to use an initialization function with an `iface_data` argument, you -must write the #GTypeInterface definitions manually. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words separated by '_'. - - - The #GType of the prerequisite type for the interface, or 0 -(%G_TYPE_INVALID) for no prerequisite type. - - - - - A convenience macro for #GTypeInterface definitions. Similar to -G_DEFINE_INTERFACE(), but allows you to insert custom code into the -*_get_type() function, e.g. additional interface implementations -via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See -G_DEFINE_TYPE_EXTENDED() for a similar example using -G_DEFINE_TYPE_WITH_CODE(). - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words separated by '_'. - - - The #GType of the prerequisite type for the interface, or 0 -(%G_TYPE_INVALID) for no prerequisite type. - - - Custom code that gets inserted in the *_get_type() function. - - - - - A convenience macro for pointer type implementations, which defines a -type_name_get_type() function registering the pointer type. - - - - The name of the new type, in Camel case - - - The name of the new type, in lowercase, with words - separated by '_' - - - - - A convenience macro for pointer type implementations. -Similar to G_DEFINE_POINTER_TYPE(), but allows to insert -custom code into the type_name_get_type() function. - - - - The name of the new type, in Camel case - - - The name of the new type, in lowercase, with words - separated by '_' - - - Custom code that gets inserted in the *_get_type() function - - - - - A convenience macro for type implementations, which declares a class -initialization function, an instance initialization function (see #GTypeInfo -for information about these) and a static variable named `t_n_parent_class` -pointing to the parent class. Furthermore, it defines a *_get_type() function. -See G_DEFINE_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - - - The most general convenience macro for type implementations, on which -G_DEFINE_TYPE(), etc are based. - -|[<!-- language="C" --> -G_DEFINE_TYPE_EXTENDED (GtkGadget, - gtk_gadget, - GTK_TYPE_WIDGET, - 0, - G_ADD_PRIVATE (GtkGadget) - G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - gtk_gadget_gizmo_init)); -]| -expands to -|[<!-- language="C" --> -static void gtk_gadget_init (GtkGadget *self); -static void gtk_gadget_class_init (GtkGadgetClass *klass); -static gpointer gtk_gadget_parent_class = NULL; -static gint GtkGadget_private_offset; -static void gtk_gadget_class_intern_init (gpointer klass) -{ - gtk_gadget_parent_class = g_type_class_peek_parent (klass); - if (GtkGadget_private_offset != 0) - g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset); - gtk_gadget_class_init ((GtkGadgetClass*) klass); -} -static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) -{ - return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset)); -} - -GType -gtk_gadget_get_type (void) -{ - static volatile gsize g_define_type_id__volatile = 0; - if (g_once_init_enter (&g_define_type_id__volatile)) - { - GType g_define_type_id = - g_type_register_static_simple (GTK_TYPE_WIDGET, - g_intern_static_string ("GtkGadget"), - sizeof (GtkGadgetClass), - (GClassInitFunc) gtk_gadget_class_intern_init, - sizeof (GtkGadget), - (GInstanceInitFunc) gtk_gadget_init, - 0); - { - GtkGadget_private_offset = - g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate)); - } - { - const GInterfaceInfo g_implement_interface_info = { - (GInterfaceInitFunc) gtk_gadget_gizmo_init - }; - g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - } - g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); - } - return g_define_type_id__volatile; -} -]| -The only pieces which have to be manually provided are the definitions of -the instance and class structure and the definitions of the instance and -class init functions. - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - #GTypeFlags to pass to g_type_register_static() - - - Custom code that gets inserted in the *_get_type() function. - - - - - A convenience macro for type implementations. -Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the -*_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). -See G_DEFINE_TYPE_EXTENDED() for an example. - - - - The name of the new type, in Camel case. - - - The name of the new type in lowercase, with words separated by '_'. - - - The #GType of the parent type. - - - Custom code that gets inserted in the *_get_type() function. - - - - - A convenience macro for type implementations, which declares a class -initialization function, an instance initialization function (see #GTypeInfo -for information about these), a static variable named `t_n_parent_class` -pointing to the parent class, and adds private instance data to the type. -Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() -for an example. - -Note that private structs added with this macros must have a struct -name of the form @TN Private. - -The private instance data can be retrieved using the automatically generated -getter function `t_n_get_instance_private()`. - -See also: G_ADD_PRIVATE() - - - - The name of the new type, in Camel case. - - - The name of the new type, in lowercase, with words - separated by '_'. - - - The #GType of the parent type. - - - - - Casts a derived #GEnumClass structure into a #GEnumClass structure. - - - - a valid #GEnumClass - - - - - Get the type identifier from a given #GEnumClass structure. - - - - a #GEnumClass - - - - - Get the static type name from a given #GEnumClass structure. - - - - a #GEnumClass - - - - - The class of an enumeration type holds information about its -possible values. - - - the parent class - - - - the smallest possible value. - - - - the largest possible value. - - - - the number of possible values. - - - - an array of #GEnumValue structs describing the - individual values. - - - - - A structure which contains a single enum value, its name, and its -nickname. - - - the enum value - - - - the name of the value - - - - the nickname of the value - - - - - Casts a derived #GFlagsClass structure into a #GFlagsClass structure. - - - - a valid #GFlagsClass - - - - - Get the type identifier from a given #GFlagsClass structure. - - - - a #GFlagsClass - - - - - Get the static type name from a given #GFlagsClass structure. - - - - a #GFlagsClass - - - - - The class of a flags type holds information about its -possible values. - - - the parent class - - - - a mask covering all possible values. - - - - the number of possible values. - - - - an array of #GFlagsValue structs describing the - individual values. - - - - - A structure which contains a single flags value, its name, and its -nickname. - - - the flags value - - - - the name of the value - - - - the nickname of the value - - - - - A convenience macro to ease interface addition in the `_C_` section -of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). -See G_DEFINE_TYPE_EXTENDED() for an example. - -Note that this macro can only be used together with the G_DEFINE_TYPE_* -macros, since it depends on variable names from those macros. - - - - The #GType of the interface to add - - - The interface init function, of type #GInterfaceInitFunc - - - - - A convenience macro to ease interface addition in the @_C_ section -of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() -for an example. - -Note that this macro can only be used together with the -G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable -names from that macro. - - - - The #GType of the interface to add - - - The interface init function - - - - - Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) -pointer. Depending on the current debugging level, this function may invoke -certain runtime checks to identify invalid casts. - - - - Object which is subject to casting. - - - - - Casts a derived #GInitiallyUnownedClass structure into a -#GInitiallyUnownedClass structure. - - - - a valid #GInitiallyUnownedClass - - - - - Get the class structure associated to a #GInitiallyUnowned instance. - - - - a #GInitiallyUnowned instance. - - - - - - - - - - - - Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM -or derived. - - - - a #GEnumClass - - - - - Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS -or derived. - - - - a #GFlagsClass - - - - - Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. - - - - Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. - - - - - Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type -%G_TYPE_INITIALLY_UNOWNED or derived. - - - - a #GInitiallyUnownedClass - - - - - Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. - - - - Instance to check for being a %G_TYPE_OBJECT. - - - - - Checks whether @class "is a" valid #GObjectClass structure of type -%G_TYPE_OBJECT or derived. - - - - a #GObjectClass - - - - - Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM -or derived. - - - - a #GParamSpec - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. - - - - a valid #GParamSpec instance - - - - - Checks whether @pclass "is a" valid #GParamSpecClass structure of type -%G_TYPE_PARAM or derived. - - - - a #GParamSpecClass - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. - - - - a #GParamSpec - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. - - - - a #GParamSpec - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. - Use #GArray instead of #GValueArray - - - - a valid #GParamSpec instance - - - - - Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. - - - - a #GParamSpec - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Checks if @value is a valid and initialized #GValue structure. - - - - A #GValue structure. - - - - - All the fields in the GInitiallyUnowned structure -are private to the #GInitiallyUnowned implementation and should never be -accessed directly. - - - - - - - - - - - - - The class structure for the GInitiallyUnowned type. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GObject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A callback function used by the type system to initialize a new -instance of a type. This function initializes all instance members and -allocates any resources required by it. - -Initialization of a derived instance involves calling all its parent -types instance initializers, so the class member of the instance -is altered during its initialization to always point to the class that -belongs to the type the current initializer was introduced for. - -The extended members of @instance are guaranteed to have been filled with -zeros before this function is called. - - - - - - - The instance to initialize - - - - The class of the type the instance is - created for - - - - - - A callback function used by the type system to finalize an interface. -This function should destroy any internal data and release any resources -allocated by the corresponding GInterfaceInitFunc() function. - - - - - - - The interface structure to finalize - - - - The @interface_data supplied via the #GInterfaceInfo structure - - - - - - A structure that provides information to the type system which is -used specifically for managing interface types. - - - location of the interface initialization function - - - - location of the interface finalization function - - - - user-supplied data passed to the interface init/finalize functions - - - - - A callback function used by the type system to initialize a new -interface. This function should initialize all internal data and -allocate any resources required by the interface. - -The members of @iface_data are guaranteed to have been filled with -zeros before this function is called. - - - - - - - The interface structure to initialize - - - - The @interface_data supplied via the #GInterfaceInfo structure - - - - - - Casts a #GObject or derived pointer into a (GObject*) pointer. -Depending on the current debugging level, this function may invoke -certain runtime checks to identify invalid casts. - - - - Object which is subject to casting. - - - - - Casts a derived #GObjectClass structure into a #GObjectClass structure. - - - - a valid #GObjectClass - - - - - Return the name of a class structure's type. - - - - a valid #GObjectClass - - - - - Get the type id of a class structure. - - - - a valid #GObjectClass - - - - - Get the class structure associated to a #GObject instance. - - - - a #GObject instance. - - - - - Get the type id of an object. - - - - Object to return the type id for. - - - - - Get the name of an object's type. - - - - Object to return the type name for. - - - - - This macro should be used to emit a standard warning about unexpected -properties in set_property() and get_property() implementations. - - - - the #GObject on which set_property() or get_property() was called - - - the numeric id of the property - - - the #GParamSpec of the property - - - - - - - - - - - - - - - - - - All the fields in the GObject structure are private -to the #GObject implementation and should never be accessed directly. - - - Creates a new instance of a #GObject subtype and sets its properties. - -Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) -which are not explicitly specified are set to their default values. - -Note that in C, small integer types in variable argument lists are promoted -up to #gint or #guint as appropriate, and read back accordingly. #gint is 32 -bits on every platform on which GLib is currently supported. This means that -you can use C expressions of type #gint with g_object_new() and properties of -type #gint or #guint or smaller. Specifically, you can use integer literals -with these property types. - -When using property types of #gint64 or #guint64, you must ensure that the -value that you provide is 64 bit. This means that you should use a cast or -make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. - -Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value -you provide is a #gdouble, even for a property of type #gfloat. - - - a new instance of - @object_type - - - - - the type id of the #GObject subtype to instantiate - - - - the name of the first property - - - - the value of the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - - - Creates a new instance of a #GObject subtype and sets its properties. - -Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) -which are not explicitly specified are set to their default values. - - - a new instance of @object_type - - - - - the type id of the #GObject subtype to instantiate - - - - the name of the first property - - - - the value of the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - - - Creates a new instance of a #GObject subtype and sets its properties using -the provided arrays. Both arrays must have exactly @n_properties elements, -and the names and values correspond by index. - -Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) -which are not explicitly specified are set to their default values. - - - a new instance of -@object_type - - - - - the object type to instantiate - - - - the number of properties - - - - the names of each property to be set - - - - - - the values of each property to be set - - - - - - - - Creates a new instance of a #GObject subtype and sets its properties. - -Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) -which are not explicitly specified are set to their default values. - Use g_object_new_with_properties() instead. -deprecated. See #GParameter for more information. - - - a new instance of -@object_type - - - - - the type id of the #GObject subtype to instantiate - - - - the length of the @parameters array - - - - an array of #GParameter - - - - - - - - - - - - - - - - - - - - - - Find the #GParamSpec with the given name for an -interface. Generally, the interface vtable passed in as @g_iface -will be the default vtable from g_type_default_interface_ref(), or, -if you know the interface has already been loaded, -g_type_default_interface_peek(). - - - the #GParamSpec for the property of the - interface with the name @property_name, or %NULL if no - such property exists. - - - - - any interface vtable for the - interface, or the default vtable for the interface - - - - name of a property to look up. - - - - - - Add a property to an interface; this is only useful for interfaces -that are added to GObject-derived types. Adding a property to an -interface forces all objects classes with that interface to have a -compatible property. The compatible property could be a newly -created #GParamSpec, but normally -g_object_class_override_property() will be used so that the object -class only needs to provide an implementation and inherits the -property description, default value, bounds, and so forth from the -interface property. - -This function is meant to be called from the interface's default -vtable initialization function (the @class_init member of -#GTypeInfo.) It must not be called after after @class_init has -been called for any object types implementing this interface. - -If @pspec is a floating reference, it will be consumed. - - - - - - - any interface vtable for the - interface, or the default - vtable for the interface. - - - - the #GParamSpec for the new property - - - - - - Lists the properties of an interface.Generally, the interface -vtable passed in as @g_iface will be the default vtable from -g_type_default_interface_ref(), or, if you know the interface has -already been loaded, g_type_default_interface_peek(). - - - a - pointer to an array of pointers to #GParamSpec - structures. The paramspecs are owned by GLib, but the - array should be freed with g_free() when you are done with - it. - - - - - - - any interface vtable for the - interface, or the default vtable for the interface - - - - location to store number of properties returned. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Emits a "notify" signal for the property @property_name on @object. - -When possible, eg. when signaling a property change from within the class -that registered the property, you should use g_object_notify_by_pspec() -instead. - -Note that emission of the notify signal may be blocked with -g_object_freeze_notify(). In this case, the signal emissions are queued -and will be emitted (in reverse order) when g_object_thaw_notify() is -called. - - - - - - - a #GObject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Increases the reference count of the object by one and sets a -callback to be called when all other references to the object are -dropped, or when this is already the last reference to the object -and another reference is established. - -This functionality is intended for binding @object to a proxy -object managed by another memory manager. This is done with two -paired references: the strong reference added by -g_object_add_toggle_ref() and a reverse reference to the proxy -object which is either a strong reference or weak reference. - -The setup is that when there are no other references to @object, -only a weak reference is held in the reverse direction from @object -to the proxy object, but when there are other references held to -@object, a strong reference is held. The @notify callback is called -when the reference from @object to the proxy object should be -"toggled" from strong to weak (@is_last_ref true) or weak to strong -(@is_last_ref false). - -Since a (normal) reference must be held to the object before -calling g_object_add_toggle_ref(), the initial state of the reverse -link is always strong. - -Multiple toggle references may be added to the same gobject, -however if there are multiple toggle references to an object, none -of them will ever be notified until all but one are removed. For -this reason, you should only ever use a toggle reference if there -is important state in the proxy object. - - - - - - - a #GObject - - - - a function to call when this reference is the - last reference to the object, or is no longer - the last reference. - - - - data to pass to @notify - - - - - - Adds a weak reference from weak_pointer to @object to indicate that -the pointer located at @weak_pointer_location is only valid during -the lifetime of @object. When the @object is finalized, -@weak_pointer will be set to %NULL. - -Note that as with g_object_weak_ref(), the weak references created by -this method are not thread-safe: they cannot safely be used in one -thread if the object's last g_object_unref() might happen in another -thread. Use #GWeakRef if thread-safety is required. - - - - - - - The object that should be weak referenced. - - - - The memory address - of a pointer. - - - - - - Creates a binding between @source_property on @source and @target_property -on @target. Whenever the @source_property is changed the @target_property is -updated using the same value. For instance: - -|[ - g_object_bind_property (action, "active", widget, "sensitive", 0); -]| - -Will result in the "sensitive" property of the widget #GObject instance to be -updated with the same value of the "active" property of the action #GObject -instance. - -If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: -if @target_property on @target changes then the @source_property on @source -will be updated as well. - -The binding will automatically be removed when either the @source or the -@target instances are finalized. To remove the binding without affecting the -@source and the @target you can just call g_object_unref() on the returned -#GBinding instance. - -A #GObject can have multiple bindings. - - - the #GBinding instance representing the - binding between the two #GObject instances. The binding is released - whenever the #GBinding reference count reaches zero. - - - - - the source #GObject - - - - the property on @source to bind - - - - the target #GObject - - - - the property on @target to bind - - - - flags to pass to #GBinding - - - - - - Complete version of g_object_bind_property(). - -Creates a binding between @source_property on @source and @target_property -on @target, allowing you to set the transformation functions to be used by -the binding. - -If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: -if @target_property on @target changes then the @source_property on @source -will be updated as well. The @transform_from function is only used in case -of bidirectional bindings, otherwise it will be ignored - -The binding will automatically be removed when either the @source or the -@target instances are finalized. This will release the reference that is -being held on the #GBinding instance; if you want to hold on to the -#GBinding instance, you will need to hold a reference to it. - -To remove the binding, call g_binding_unbind(). - -A #GObject can have multiple bindings. - -The same @user_data parameter will be used for both @transform_to -and @transform_from transformation functions; the @notify function will -be called once, when the binding is removed. If you need different data -for each transformation function, please use -g_object_bind_property_with_closures() instead. - - - the #GBinding instance representing the - binding between the two #GObject instances. The binding is released - whenever the #GBinding reference count reaches zero. - - - - - the source #GObject - - - - the property on @source to bind - - - - the target #GObject - - - - the property on @target to bind - - - - flags to pass to #GBinding - - - - the transformation function - from the @source to the @target, or %NULL to use the default - - - - the transformation function - from the @target to the @source, or %NULL to use the default - - - - custom data to be passed to the transformation functions, - or %NULL - - - - a function to call when disposing the binding, to free - resources used by the transformation functions, or %NULL if not required - - - - - - Creates a binding between @source_property on @source and @target_property -on @target, allowing you to set the transformation functions to be used by -the binding. - -This function is the language bindings friendly version of -g_object_bind_property_full(), using #GClosures instead of -function pointers. - - - the #GBinding instance representing the - binding between the two #GObject instances. The binding is released - whenever the #GBinding reference count reaches zero. - - - - - the source #GObject - - - - the property on @source to bind - - - - the target #GObject - - - - the property on @target to bind - - - - flags to pass to #GBinding - - - - a #GClosure wrapping the transformation function - from the @source to the @target, or %NULL to use the default - - - - a #GClosure wrapping the transformation function - from the @target to the @source, or %NULL to use the default - - - - - - A convenience function to connect multiple signals at once. - -The signal specs expected by this function have the form -"modifier::signal_name", where modifier can be one of the following: -- signal: equivalent to g_signal_connect_data (..., NULL, 0) -- object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) -- swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) -- swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) -- signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) -- object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) -- swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) -- swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) - -|[<!-- language="C" --> - menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, - "type", GTK_WINDOW_POPUP, - "child", menu, - NULL), - "signal::event", gtk_menu_window_event, menu, - "signal::size_request", gtk_menu_window_size_request, menu, - "signal::destroy", gtk_widget_destroyed, &menu->toplevel, - NULL); -]| - - - @object - - - - - a #GObject - - - - the spec for the first signal - - - - #GCallback for the first signal, followed by data for the - first signal, followed optionally by more signal - spec/callback/data triples, followed by %NULL - - - - - - A convenience function to disconnect multiple signals at once. - -The signal specs expected by this function have the form -"any_signal", which means to disconnect any signal with matching -callback and data, or "any_signal::signal_name", which only -disconnects the signal named "signal_name". - - - - - - - a #GObject - - - - the spec for the first signal - - - - #GCallback for the first signal, followed by data for the first signal, - followed optionally by more signal spec/callback/data triples, - followed by %NULL - - - - - - This is a variant of g_object_get_data() which returns -a 'duplicate' of the value. @dup_func defines the -meaning of 'duplicate' in this context, it could e.g. -take a reference on a ref-counted object. - -If the @key is not set on the object then @dup_func -will be called with a %NULL argument. - -Note that @dup_func is called while user data of @object -is locked. - -This function can be useful to avoid races when multiple -threads are using object data on the same key on the same -object. - - - the result of calling @dup_func on the value - associated with @key on @object, or %NULL if not set. - If @dup_func is %NULL, the value is returned - unmodified. - - - - - the #GObject to store user data on - - - - a string, naming the user data pointer - - - - function to dup the value - - - - passed as user_data to @dup_func - - - - - - This is a variant of g_object_get_qdata() which returns -a 'duplicate' of the value. @dup_func defines the -meaning of 'duplicate' in this context, it could e.g. -take a reference on a ref-counted object. - -If the @quark is not set on the object then @dup_func -will be called with a %NULL argument. - -Note that @dup_func is called while user data of @object -is locked. - -This function can be useful to avoid races when multiple -threads are using object data on the same key on the same -object. - - - the result of calling @dup_func on the value - associated with @quark on @object, or %NULL if not set. - If @dup_func is %NULL, the value is returned - unmodified. - - - - - the #GObject to store user data on - - - - a #GQuark, naming the user data pointer - - - - function to dup the value - - - - passed as user_data to @dup_func - - - - - - This function is intended for #GObject implementations to re-enforce -a [floating][floating-ref] object reference. Doing this is seldom -required: all #GInitiallyUnowneds are created with a floating reference -which usually just needs to be sunken by calling g_object_ref_sink(). - - - - - - - a #GObject - - - - - - Increases the freeze count on @object. If the freeze count is -non-zero, the emission of "notify" signals on @object is -stopped. The signals are queued until the freeze count is decreased -to zero. Duplicate notifications are squashed so that at most one -#GObject::notify signal is emitted for each property modified while the -object is frozen. - -This is necessary for accessors that modify multiple properties to prevent -premature notification while the object is still being modified. - - - - - - - a #GObject - - - - - - Gets properties of an object. - -In general, a copy is made of the property contents and the caller -is responsible for freeing the memory in the appropriate manner for -the type, for instance by calling g_free() or g_object_unref(). - -Here is an example of using g_object_get() to get the contents -of three properties: an integer, a string and an object: -|[<!-- language="C" --> - gint intval; - guint64 uint64val; - gchar *strval; - GObject *objval; - - g_object_get (my_object, - "int-property", &intval, - "uint64-property", &uint64val, - "str-property", &strval, - "obj-property", &objval, - NULL); - - // Do something with intval, uint64val, strval, objval - - g_free (strval); - g_object_unref (objval); -]| - - - - - - - a #GObject - - - - name of the first property to get - - - - return location for the first property, followed optionally by more - name/return location pairs, followed by %NULL - - - - - - Gets a named field from the objects table of associations (see g_object_set_data()). - - - the data if found, - or %NULL if no such data exists. - - - - - #GObject containing the associations - - - - name of the key for that association - - - - - - Gets a property of an object. - -The @value can be: - - - an empty #GValue initialized by %G_VALUE_INIT, which will be - automatically initialized with the expected type of the property - (since GLib 2.60) - - a #GValue initialized with the expected type of the property - - a #GValue initialized with a type to which the expected type - of the property can be transformed - -In general, a copy is made of the property contents and the caller is -responsible for freeing the memory by calling g_value_unset(). - -Note that g_object_get_property() is really intended for language -bindings, g_object_get() is much more convenient for C programming. - - - - - - - a #GObject - - - - the name of the property to get - - - - return location for the property value - - - - - - This function gets back user data pointers stored via -g_object_set_qdata(). - - - The user data pointer set, or %NULL - - - - - The GObject to get a stored user data pointer from - - - - A #GQuark, naming the user data pointer - - - - - - Gets properties of an object. - -In general, a copy is made of the property contents and the caller -is responsible for freeing the memory in the appropriate manner for -the type, for instance by calling g_free() or g_object_unref(). - -See g_object_get(). - - - - - - - a #GObject - - - - name of the first property to get - - - - return location for the first property, followed optionally by more - name/return location pairs, followed by %NULL - - - - - - Gets @n_properties properties for an @object. -Obtained properties will be set to @values. All properties must be valid. -Warnings will be emitted and undefined behaviour may result if invalid -properties are passed in. - - - - - - - a #GObject - - - - the number of properties - - - - the names of each property to get - - - - - - the values of each property to get - - - - - - - - Checks whether @object has a [floating][floating-ref] reference. - - - %TRUE if @object has a floating reference - - - - - a #GObject - - - - - - Emits a "notify" signal for the property @property_name on @object. - -When possible, eg. when signaling a property change from within the class -that registered the property, you should use g_object_notify_by_pspec() -instead. - -Note that emission of the notify signal may be blocked with -g_object_freeze_notify(). In this case, the signal emissions are queued -and will be emitted (in reverse order) when g_object_thaw_notify() is -called. - - - - - - - a #GObject - - - - the name of a property installed on the class of @object. - - - - - - Emits a "notify" signal for the property specified by @pspec on @object. - -This function omits the property name lookup, hence it is faster than -g_object_notify(). - -One way to avoid using g_object_notify() from within the -class that registered the properties, and using g_object_notify_by_pspec() -instead, is to store the GParamSpec used with -g_object_class_install_property() inside a static array, e.g.: - -|[<!-- language="C" --> - enum - { - PROP_0, - PROP_FOO, - PROP_LAST - }; - - static GParamSpec *properties[PROP_LAST]; - - static void - my_object_class_init (MyObjectClass *klass) - { - properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", - 0, 100, - 50, - G_PARAM_READWRITE); - g_object_class_install_property (gobject_class, - PROP_FOO, - properties[PROP_FOO]); - } -]| - -and then notify a change on the "foo" property with: - -|[<!-- language="C" --> - g_object_notify_by_pspec (self, properties[PROP_FOO]); -]| - - - - - - - a #GObject - - - - the #GParamSpec of a property installed on the class of @object. - - - - - - Increases the reference count of @object. - -Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type -of @object will be propagated to the return type (using the GCC typeof() -extension), so any casting the caller needs to do on the return type must be -explicit. - - - the same @object - - - - - a #GObject - - - - - - Increase the reference count of @object, and possibly remove the -[floating][floating-ref] reference, if @object has a floating reference. - -In other words, if the object is floating, then this call "assumes -ownership" of the floating reference, converting it to a normal -reference by clearing the floating flag while leaving the reference -count unchanged. If the object is not floating, then this call -adds a new normal reference increasing the reference count by one. - -Since GLib 2.56, the type of @object will be propagated to the return type -under the same conditions as for g_object_ref(). - - - @object - - - - - a #GObject - - - - - - Removes a reference added with g_object_add_toggle_ref(). The -reference count of the object is decreased by one. - - - - - - - a #GObject - - - - a function to call when this reference is the - last reference to the object, or is no longer - the last reference. - - - - data to pass to @notify - - - - - - Removes a weak reference from @object that was previously added -using g_object_add_weak_pointer(). The @weak_pointer_location has -to match the one used with g_object_add_weak_pointer(). - - - - - - - The object that is weak referenced. - - - - The memory address - of a pointer. - - - - - - Compares the user data for the key @key on @object with -@oldval, and if they are the same, replaces @oldval with -@newval. - -This is like a typical atomic compare-and-exchange -operation, for user data on an object. - -If the previous value was replaced then ownership of the -old value (@oldval) is passed to the caller, including -the registered destroy notify for it (passed out in @old_destroy). -It’s up to the caller to free this as needed, which may -or may not include using @old_destroy as sometimes replacement -should not destroy the object in the normal way. - -See g_object_set_data() for guidance on using a small, bounded set of values -for @key. - - - %TRUE if the existing value for @key was replaced - by @newval, %FALSE otherwise. - - - - - the #GObject to store user data on - - - - a string, naming the user data pointer - - - - the old value to compare against - - - - the new value - - - - a destroy notify for the new value - - - - destroy notify for the existing value - - - - - - Compares the user data for the key @quark on @object with -@oldval, and if they are the same, replaces @oldval with -@newval. - -This is like a typical atomic compare-and-exchange -operation, for user data on an object. - -If the previous value was replaced then ownership of the -old value (@oldval) is passed to the caller, including -the registered destroy notify for it (passed out in @old_destroy). -It’s up to the caller to free this as needed, which may -or may not include using @old_destroy as sometimes replacement -should not destroy the object in the normal way. - - - %TRUE if the existing value for @quark was replaced - by @newval, %FALSE otherwise. - - - - - the #GObject to store user data on - - - - a #GQuark, naming the user data pointer - - - - the old value to compare against - - - - the new value - - - - a destroy notify for the new value - - - - destroy notify for the existing value - - - - - - Releases all references to other objects. This can be used to break -reference cycles. - -This function should only be called from object system implementations. - - - - - - - a #GObject - - - - - - Sets properties on an object. - -The same caveats about passing integer literals as varargs apply as with -g_object_new(). In particular, any integer literals set as the values for -properties of type #gint64 or #guint64 must be 64 bits wide, using the -%G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. - -Note that the "notify" signals are queued and only emitted (in -reverse order) after all properties have been set. See -g_object_freeze_notify(). - - - - - - - a #GObject - - - - name of the first property to set - - - - value for the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - - - Each object carries around a table of associations from -strings to pointers. This function lets you set an association. - -If the object already had an association with that name, -the old association will be destroyed. - -Internally, the @key is converted to a #GQuark using g_quark_from_string(). -This means a copy of @key is kept permanently (even after @object has been -finalized) — so it is recommended to only use a small, bounded set of values -for @key in your program, to avoid the #GQuark storage growing unbounded. - - - - - - - #GObject containing the associations. - - - - name of the key - - - - data to associate with that key - - - - - - Like g_object_set_data() except it adds notification -for when the association is destroyed, either by setting it -to a different value or when the object is destroyed. - -Note that the @destroy callback is not called if @data is %NULL. - - - - - - - #GObject containing the associations - - - - name of the key - - - - data to associate with that key - - - - function to call when the association is destroyed - - - - - - Sets a property on an object. - - - - - - - a #GObject - - - - the name of the property to set - - - - the value - - - - - - This sets an opaque, named pointer on an object. -The name is specified through a #GQuark (retrived e.g. via -g_quark_from_static_string()), and the pointer -can be gotten back from the @object with g_object_get_qdata() -until the @object is finalized. -Setting a previously set user data pointer, overrides (frees) -the old pointer set, using #NULL as pointer essentially -removes the data stored. - - - - - - - The GObject to set store a user data pointer - - - - A #GQuark, naming the user data pointer - - - - An opaque user data pointer - - - - - - This function works like g_object_set_qdata(), but in addition, -a void (*destroy) (gpointer) function may be specified which is -called with @data as argument when the @object is finalized, or -the data is being overwritten by a call to g_object_set_qdata() -with the same @quark. - - - - - - - The GObject to set store a user data pointer - - - - A #GQuark, naming the user data pointer - - - - An opaque user data pointer - - - - Function to invoke with @data as argument, when @data - needs to be freed - - - - - - Sets properties on an object. - - - - - - - a #GObject - - - - name of the first property to set - - - - value for the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - - - Sets @n_properties properties for an @object. -Properties to be set will be taken from @values. All properties must be -valid. Warnings will be emitted and undefined behaviour may result if invalid -properties are passed in. - - - - - - - a #GObject - - - - the number of properties - - - - the names of each property to be set - - - - - - the values of each property to be set - - - - - - - - Remove a specified datum from the object's data associations, -without invoking the association's destroy handler. - - - the data if found, or %NULL - if no such data exists. - - - - - #GObject containing the associations - - - - name of the key - - - - - - This function gets back user data pointers stored via -g_object_set_qdata() and removes the @data from object -without invoking its destroy() function (if any was -set). -Usually, calling this function is only required to update -user data pointers with a destroy notifier, for example: -|[<!-- language="C" --> -void -object_add_to_user_list (GObject *object, - const gchar *new_string) -{ - // the quark, naming the object data - GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - // retrive the old string list - GList *list = g_object_steal_qdata (object, quark_string_list); - - // prepend new string - list = g_list_prepend (list, g_strdup (new_string)); - // this changed 'list', so we need to set it again - g_object_set_qdata_full (object, quark_string_list, list, free_string_list); -} -static void -free_string_list (gpointer data) -{ - GList *node, *list = data; - - for (node = list; node; node = node->next) - g_free (node->data); - g_list_free (list); -} -]| -Using g_object_get_qdata() in the above example, instead of -g_object_steal_qdata() would have left the destroy function set, -and thus the partial string list would have been freed upon -g_object_set_qdata_full(). - - - The user data pointer set, or %NULL - - - - - The GObject to get a stored user data pointer from - - - - A #GQuark, naming the user data pointer - - - - - - Reverts the effect of a previous call to -g_object_freeze_notify(). The freeze count is decreased on @object -and when it reaches zero, queued "notify" signals are emitted. - -Duplicate notifications for each property are squashed so that at most one -#GObject::notify signal is emitted for each property, in the reverse order -in which they have been queued. - -It is an error to call this function when the freeze count is zero. - - - - - - - a #GObject - - - - - - Decreases the reference count of @object. When its reference count -drops to 0, the object is finalized (i.e. its memory is freed). - -If the pointer to the #GObject may be reused in future (for example, if it is -an instance variable of another object), it is recommended to clear the -pointer to %NULL rather than retain a dangling pointer to a potentially -invalid #GObject instance. Use g_clear_object() for this. - - - - - - - a #GObject - - - - - - This function essentially limits the life time of the @closure to -the life time of the object. That is, when the object is finalized, -the @closure is invalidated by calling g_closure_invalidate() on -it, in order to prevent invocations of the closure with a finalized -(nonexisting) object. Also, g_object_ref() and g_object_unref() are -added as marshal guards to the @closure, to ensure that an extra -reference count is held on @object during invocation of the -@closure. Usually, this function will be called on closures that -use this @object as closure data. - - - - - - - #GObject restricting lifetime of @closure - - - - #GClosure to watch - - - - - - Adds a weak reference callback to an object. Weak references are -used for notification when an object is finalized. They are called -"weak references" because they allow you to safely hold a pointer -to an object without calling g_object_ref() (g_object_ref() adds a -strong reference, that is, forces the object to stay alive). - -Note that the weak references created by this method are not -thread-safe: they cannot safely be used in one thread if the -object's last g_object_unref() might happen in another thread. -Use #GWeakRef if thread-safety is required. - - - - - - - #GObject to reference weakly - - - - callback to invoke before the object is freed - - - - extra data to pass to notify - - - - - - Removes a weak reference callback to an object. - - - - - - - #GObject to remove a weak reference from - - - - callback to search for - - - - data to search for - - - - - - - - - - - - - - - The notify signal is emitted on an object when one of its properties has -its value set through g_object_set_property(), g_object_set(), et al. - -Note that getting this signal doesn’t itself guarantee that the value of -the property has actually changed. When it is emitted is determined by the -derived GObject class. If the implementor did not create the property with -%G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results -in ::notify being emitted, even if the new value is the same as the old. -If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only -when they explicitly call g_object_notify() or g_object_notify_by_pspec(), -and common practice is to do that only when the value has actually changed. - -This signal is typically used to obtain change notification for a -single property, by specifying the property name as a detail in the -g_signal_connect() call, like this: -|[<!-- language="C" --> -g_signal_connect (text_view->buffer, "notify::paste-target-list", - G_CALLBACK (gtk_text_view_target_list_notify), - text_view) -]| -It is important to note that you must use -[canonical parameter names][canonical-parameter-names] as -detail strings for the notify signal. - - - - - - the #GParamSpec of the property which changed. - - - - - - - The class structure for the GObject type. - -|[<!-- language="C" --> -// Example of implementing a singleton using a constructor. -static MySingleton *the_singleton = NULL; - -static GObject* -my_singleton_constructor (GType type, - guint n_construct_params, - GObjectConstructParam *construct_params) -{ - GObject *object; - - if (!the_singleton) - { - object = G_OBJECT_CLASS (parent_class)->constructor (type, - n_construct_params, - construct_params); - the_singleton = MY_SINGLETON (object); - } - else - object = g_object_ref (G_OBJECT (the_singleton)); - - return object; -} -]| - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GObject - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Looks up the #GParamSpec for a property of a class. - - - the #GParamSpec for the property, or - %NULL if the class doesn't have a property of that name - - - - - a #GObjectClass - - - - the name of the property to look up - - - - - - Installs new properties from an array of #GParamSpecs. - -All properties should be installed during the class initializer. It -is possible to install properties after that, but doing so is not -recommend, and specifically, is not guaranteed to be thread-safe vs. -use of properties on the same type on other threads. - -The property id of each property is the index of each #GParamSpec in -the @pspecs array. - -The property id of 0 is treated specially by #GObject and it should not -be used to store a #GParamSpec. - -This function should be used if you plan to use a static array of -#GParamSpecs and g_object_notify_by_pspec(). For instance, this -class initialization: - -|[<!-- language="C" --> -enum { - PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES -}; - -static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; - -static void -my_object_class_init (MyObjectClass *klass) -{ - GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - - obj_properties[PROP_FOO] = - g_param_spec_int ("foo", "Foo", "Foo", - -1, G_MAXINT, - 0, - G_PARAM_READWRITE); - - obj_properties[PROP_BAR] = - g_param_spec_string ("bar", "Bar", "Bar", - NULL, - G_PARAM_READWRITE); - - gobject_class->set_property = my_object_set_property; - gobject_class->get_property = my_object_get_property; - g_object_class_install_properties (gobject_class, - N_PROPERTIES, - obj_properties); -} -]| - -allows calling g_object_notify_by_pspec() to notify of property changes: - -|[<!-- language="C" --> -void -my_object_set_foo (MyObject *self, gint foo) -{ - if (self->foo != foo) - { - self->foo = foo; - g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); - } - } -]| - - - - - - - a #GObjectClass - - - - the length of the #GParamSpecs array - - - - the #GParamSpecs array - defining the new properties - - - - - - - - Installs a new property. - -All properties should be installed during the class initializer. It -is possible to install properties after that, but doing so is not -recommend, and specifically, is not guaranteed to be thread-safe vs. -use of properties on the same type on other threads. - -Note that it is possible to redefine a property in a derived class, -by installing a property with the same name. This can be useful at times, -e.g. to change the range of allowed values or the default value. - - - - - - - a #GObjectClass - - - - the id for the new property - - - - the #GParamSpec for the new property - - - - - - Get an array of #GParamSpec* for all properties of a class. - - - an array of - #GParamSpec* which should be freed after use - - - - - - - a #GObjectClass - - - - return location for the length of the returned array - - - - - - Registers @property_id as referring to a property with the name -@name in a parent class or in an interface implemented by @oclass. -This allows this class to "override" a property implementation in -a parent class or to provide the implementation of a property from -an interface. - -Internally, overriding is implemented by creating a property of type -#GParamSpecOverride; generally operations that query the properties of -the object class, such as g_object_class_find_property() or -g_object_class_list_properties() will return the overridden -property. However, in one case, the @construct_properties argument of -the @constructor virtual function, the #GParamSpecOverride is passed -instead, so that the @param_id field of the #GParamSpec will be -correct. For virtually all uses, this makes no difference. If you -need to get the overridden property, you can call -g_param_spec_get_redirect_target(). - - - - - - - a #GObjectClass - - - - the new property ID - - - - the name of a property registered in a parent class or - in an interface of this class. - - - - - - - The GObjectConstructParam struct is an auxiliary -structure used to hand #GParamSpec/#GValue pairs to the @constructor of -a #GObjectClass. - - - the #GParamSpec of the construct parameter - - - - the value to set the parameter to - - - - - The type of the @finalize function of #GObjectClass. - - - - - - - the #GObject being finalized - - - - - - The type of the @get_property function of #GObjectClass. - - - - - - - a #GObject - - - - the numeric id under which the property was registered with - g_object_class_install_property(). - - - - a #GValue to return the property value in - - - - the #GParamSpec describing the property - - - - - - The type of the @set_property function of #GObjectClass. - - - - - - - a #GObject - - - - the numeric id under which the property was registered with - g_object_class_install_property(). - - - - the new value for the property - - - - the #GParamSpec describing the property - - - - - - Mask containing the bits of #GParamSpec.flags which are reserved for GLib. - - - - - Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into -a #GParamSpec object. - - - - a valid #GParamSpec - - - - - Cast a #GParamSpec instance into a #GParamSpecBoolean. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecBoxed. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecChar. - - - - a valid #GParamSpec instance - - - - - Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. - - - - a valid #GParamSpecClass - - - - - Cast a #GParamSpec instance into a #GParamSpecDouble. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecEnum. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecFlags. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecFloat. - - - - a valid #GParamSpec instance - - - - - Retrieves the #GParamSpecClass of a #GParamSpec. - - - - a valid #GParamSpec - - - - - Casts a #GParamSpec into a #GParamSpecGType. - - - - a #GParamSpec - - - - - Cast a #GParamSpec instance into a #GParamSpecInt. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecInt64. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecLong. - - - - a valid #GParamSpec instance - - - - - Casts a #GParamSpec instance into a #GParamSpecObject. - - - - a valid #GParamSpec instance - - - - - Casts a #GParamSpec into a #GParamSpecOverride. - - - - a #GParamSpec - - - - - Casts a #GParamSpec instance into a #GParamSpecParam. - - - - a valid #GParamSpec instance - - - - - Casts a #GParamSpec instance into a #GParamSpecPointer. - - - - a valid #GParamSpec instance - - - - - Casts a #GParamSpec instance into a #GParamSpecString. - - - - a valid #GParamSpec instance - - - - - Retrieves the #GType of this @pspec. - - - - a valid #GParamSpec - - - - - Retrieves the #GType name of this @pspec. - - - - a valid #GParamSpec - - - - - Cast a #GParamSpec instance into a #GParamSpecUChar. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecUInt. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecUInt64. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecULong. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecUnichar. - - - - a valid #GParamSpec instance - - - - - Cast a #GParamSpec instance into a #GParamSpecValueArray. - Use #GArray instead of #GValueArray - - - - a valid #GParamSpec instance - - - - - Retrieves the #GType to initialize a #GValue for this parameter. - - - - a valid #GParamSpec - - - - - Casts a #GParamSpec into a #GParamSpecVariant. - - - - a #GParamSpec - - - - - #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. - -Since 2.13.0 - - - - - Minimum shift count to be used for user defined flags, to be stored in -#GParamSpec.flags. The maximum allowed is 10. - - - - - Evaluates to the @field_name inside the @inst private data -structure for @TypeName. - -Note that this macro can only be used together with the G_DEFINE_TYPE_* -and G_ADD_PRIVATE() macros, since it depends on variable names from -those macros. - - - - the name of the type in CamelCase - - - the instance of @TypeName you wish to access - - - the type of the field in the private data structure - - - the name of the field in the private data structure - - - - - Evaluates to a pointer to the @field_name inside the @inst private data -structure for @TypeName. - -Note that this macro can only be used together with the G_DEFINE_TYPE_* -and G_ADD_PRIVATE() macros, since it depends on variable names from -those macros. - - - - the name of the type in CamelCase - - - the instance of @TypeName you wish to access - - - the name of the field in the private data structure - - - - - Evaluates to the offset of the @field inside the instance private data -structure for @TypeName. - -Note that this macro can only be used together with the G_DEFINE_TYPE_* -and G_ADD_PRIVATE() macros, since it depends on variable names from -those macros. - - - - the name of the type in CamelCase - - - the name of the field in the private data structure - - - - - Through the #GParamFlags flag values, certain aspects of parameters -can be configured. See also #G_PARAM_STATIC_STRINGS. - - - the parameter is readable - - - the parameter is writable - - - alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE - - - the parameter will be set upon object construction - - - the parameter can only be set upon object construction - - - upon parameter conversion (see g_param_value_convert()) - strict validation is not required - - - the string used as name when constructing the - parameter is guaranteed to remain valid and - unmodified for the lifetime of the parameter. - Since 2.8 - - - internal - - - the string used as nick when constructing the - parameter is guaranteed to remain valid and - unmmodified for the lifetime of the parameter. - Since 2.8 - - - the string used as blurb when constructing the - parameter is guaranteed to remain valid and - unmodified for the lifetime of the parameter. - Since 2.8 - - - calls to g_object_set_property() for this - property will not automatically result in a "notify" signal being - emitted: the implementation must call g_object_notify() themselves - in case the property actually changes. Since: 2.42. - - - the parameter is deprecated and will be removed - in a future version. A warning will be generated if it is used - while running with G_ENABLE_DIAGNOSTIC=1. - Since 2.26 - - - - #GParamSpec is an object structure that encapsulates the metadata -required to specify parameters, such as e.g. #GObject properties. - -## Parameter names # {#canonical-parameter-names} - -A property name consists of segments consisting of ASCII letters and -digits, separated by either the `-` or `_` character. The first -character of a property name must be a letter. These are the same rules as -for signal naming (see g_signal_new()). - -When creating and looking up a #GParamSpec, either separator can be -used, but they cannot be mixed. Using `-` is considerably more -efficient, and is the ‘canonical form’. Using `_` is discouraged. - - - Creates a new #GParamSpec instance. - -See [canonical parameter names][canonical-parameter-names] for details of -the rules for @name. Names which violate these rules lead to undefined -behaviour. - -Beyond the name, #GParamSpecs have two more descriptive -strings associated with them, the @nick, which should be suitable -for use as a label for the property in a property editor, and the -@blurb, which should be a somewhat longer description, suitable for -e.g. a tooltip. The @nick and @blurb should ideally be localized. - - - a newly allocated #GParamSpec instance - - - - - the #GType for the property; must be derived from #G_TYPE_PARAM - - - - the canonical name of the property - - - - the nickname of the property - - - - a short description of the property - - - - a combination of #GParamFlags - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the short description of a #GParamSpec. - - - the short description of @pspec. - - - - - a valid #GParamSpec - - - - - - Gets the default value of @pspec as a pointer to a #GValue. - -The #GValue will remain valid for the life of @pspec. - - - a pointer to a #GValue which must not be modified - - - - - a #GParamSpec - - - - - - Get the name of a #GParamSpec. - -The name is always an "interned" string (as per g_intern_string()). -This allows for pointer-value comparisons. - - - the name of @pspec. - - - - - a valid #GParamSpec - - - - - - Gets the GQuark for the name. - - - the GQuark for @pspec->name. - - - - - a #GParamSpec - - - - - - Get the nickname of a #GParamSpec. - - - the nickname of @pspec. - - - - - a valid #GParamSpec - - - - - - Gets back user data pointers stored via g_param_spec_set_qdata(). - - - the user data pointer set, or %NULL - - - - - a valid #GParamSpec - - - - a #GQuark, naming the user data pointer - - - - - - If the paramspec redirects operations to another paramspec, -returns that paramspec. Redirect is used typically for -providing a new implementation of a property in a derived -type while preserving all the properties from the parent -type. Redirection is established by creating a property -of type #GParamSpecOverride. See g_object_class_override_property() -for an example of the use of this capability. - - - paramspec to which requests on this - paramspec should be redirected, or %NULL if none. - - - - - a #GParamSpec - - - - - - Increments the reference count of @pspec. - - - the #GParamSpec that was passed into this function - - - - - a valid #GParamSpec - - - - - - Convenience function to ref and sink a #GParamSpec. - - - the #GParamSpec that was passed into this function - - - - - a valid #GParamSpec - - - - - - Sets an opaque, named pointer on a #GParamSpec. The name is -specified through a #GQuark (retrieved e.g. via -g_quark_from_static_string()), and the pointer can be gotten back -from the @pspec with g_param_spec_get_qdata(). Setting a -previously set user data pointer, overrides (frees) the old pointer -set, using %NULL as pointer essentially removes the data stored. - - - - - - - the #GParamSpec to set store a user data pointer - - - - a #GQuark, naming the user data pointer - - - - an opaque user data pointer - - - - - - This function works like g_param_spec_set_qdata(), but in addition, -a `void (*destroy) (gpointer)` function may be -specified which is called with @data as argument when the @pspec is -finalized, or the data is being overwritten by a call to -g_param_spec_set_qdata() with the same @quark. - - - - - - - the #GParamSpec to set store a user data pointer - - - - a #GQuark, naming the user data pointer - - - - an opaque user data pointer - - - - function to invoke with @data as argument, when @data needs to - be freed - - - - - - The initial reference count of a newly created #GParamSpec is 1, -even though no one has explicitly called g_param_spec_ref() on it -yet. So the initial reference count is flagged as "floating", until -someone calls `g_param_spec_ref (pspec); g_param_spec_sink -(pspec);` in sequence on it, taking over the initial -reference count (thus ending up with a @pspec that has a reference -count of 1 still, but is not flagged "floating" anymore). - - - - - - - a valid #GParamSpec - - - - - - Gets back user data pointers stored via g_param_spec_set_qdata() -and removes the @data from @pspec without invoking its destroy() -function (if any was set). Usually, calling this function is only -required to update user data pointers with a destroy notifier. - - - the user data pointer set, or %NULL - - - - - the #GParamSpec to get a stored user data pointer from - - - - a #GQuark, naming the user data pointer - - - - - - Decrements the reference count of a @pspec. - - - - - - - a valid #GParamSpec - - - - - - private #GTypeInstance portion - - - - name of this parameter: always an interned string - - - - #GParamFlags flags for this parameter - - - - the #GValue type for this parameter - - - - #GType type that uses (introduces) this parameter - - - - - - - - - - - - - - - - - - - - A #GParamSpec derived structure that contains the meta data for boolean properties. - - private #GParamSpec portion - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for boxed properties. - - private #GParamSpec portion - - - - - A #GParamSpec derived structure that contains the meta data for character properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - The class structure for the GParamSpec type. -Normally, GParamSpec classes are filled by -g_param_type_register_static(). - - - the parent class - - - - the #GValue type for this parameter - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GParamSpec derived structure that contains the meta data for double properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - values closer than @epsilon will be considered identical - by g_param_values_cmp(); the default value is 1e-90. - - - - - A #GParamSpec derived structure that contains the meta data for enum -properties. - - private #GParamSpec portion - - - - the #GEnumClass for the enum - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for flags -properties. - - private #GParamSpec portion - - - - the #GFlagsClass for the flags - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for float properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - values closer than @epsilon will be considered identical - by g_param_values_cmp(); the default value is 1e-30. - - - - - A #GParamSpec derived structure that contains the meta data for #GType properties. - - private #GParamSpec portion - - - - a #GType whose subtypes can occur as values - - - - - A #GParamSpec derived structure that contains the meta data for integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for 64bit integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for long integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for object properties. - - private #GParamSpec portion - - - - - This is a type of #GParamSpec type that simply redirects operations to -another paramspec. All operations other than getting or -setting the value are redirected, including accessing the nick and -blurb, validating a value, and so forth. See -g_param_spec_get_redirect_target() for retrieving the overidden -property. #GParamSpecOverride is used in implementing -g_object_class_override_property(), and will not be directly useful -unless you are implementing a new base type similar to GObject. - - - - - - - - - A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM -properties. - - private #GParamSpec portion - - - - - A #GParamSpec derived structure that contains the meta data for pointer properties. - - private #GParamSpec portion - - - - - A #GParamSpecPool maintains a collection of #GParamSpecs which can be -quickly accessed by owner and name. The implementation of the #GObject property -system uses such a pool to store the #GParamSpecs of the properties all object -types. - - - Inserts a #GParamSpec in the pool. - - - - - - - a #GParamSpecPool. - - - - the #GParamSpec to insert - - - - a #GType identifying the owner of @pspec - - - - - - Gets an array of all #GParamSpecs owned by @owner_type in -the pool. - - - a newly - allocated array containing pointers to all #GParamSpecs - owned by @owner_type in the pool - - - - - - - a #GParamSpecPool - - - - the owner to look for - - - - return location for the length of the returned array - - - - - - Gets an #GList of all #GParamSpecs owned by @owner_type in -the pool. - - - a - #GList of all #GParamSpecs owned by @owner_type in - the pool#GParamSpecs. - - - - - - - a #GParamSpecPool - - - - the owner to look for - - - - - - Looks up a #GParamSpec in the pool. - - - The found #GParamSpec, or %NULL if no -matching #GParamSpec was found. - - - - - a #GParamSpecPool - - - - the name to look for - - - - the owner to look for - - - - If %TRUE, also try to find a #GParamSpec with @param_name - owned by an ancestor of @owner_type. - - - - - - Removes a #GParamSpec from the pool. - - - - - - - a #GParamSpecPool - - - - the #GParamSpec to remove - - - - - - Creates a new #GParamSpecPool. - -If @type_prefixing is %TRUE, lookups in the newly created pool will -allow to specify the owner as a colon-separated prefix of the -property name, like "GtkContainer:border-width". This feature is -deprecated, so you should always set @type_prefixing to %FALSE. - - - a newly allocated #GParamSpecPool. - - - - - Whether the pool will support type-prefixed property names. - - - - - - - A #GParamSpec derived structure that contains the meta data for string -properties. - - private #GParamSpec portion - - - - default value for the property specified - - - - a string containing the allowed values for the first byte - - - - a string containing the allowed values for the subsequent bytes - - - - the replacement byte for bytes which don't match @cset_first or @cset_nth. - - - - replace empty string by %NULL - - - - replace %NULL strings by an empty string - - - - - This structure is used to provide the type system with the information -required to initialize and destruct (finalize) a parameter's class and -instances thereof. -The initialized structure is passed to the g_param_type_register_static() -The type system will perform a deep copy of this structure, so its memory -does not need to be persistent across invocation of -g_param_type_register_static(). - - - Size of the instance (object) structure. - - - - Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. - - - - - - - - - - - - - - - - - The #GType of values conforming to this #GParamSpec - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GParamSpec derived structure that contains the meta data for unsigned character properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for unsigned integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. - - private #GParamSpec portion - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. - - private #GParamSpec portion - - - - default value for the property specified - - - - - A #GParamSpec derived structure that contains the meta data for #GValueArray properties. - - private #GParamSpec portion - - - - a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - - - - if greater than 0, arrays of this property will always have this many elements - - - - - A #GParamSpec derived structure that contains the meta data for #GVariant properties. - -When comparing values with g_param_values_cmp(), scalar values with the same -type will be compared with g_variant_compare(). Other non-%NULL variants will -be checked for equality with g_variant_equal(), and their sort order is -otherwise undefined. %NULL is ordered before non-%NULL variants. Two %NULL -values compare equal. - - private #GParamSpec portion - - - - a #GVariantType, or %NULL - - - - a #GVariant, or %NULL - - - - - - - - - - The GParameter struct is an auxiliary structure used -to hand parameter name/value pairs to g_object_newv(). - This type is not introspectable. - - - the parameter name - - - - the parameter value - - - - - A mask for all #GSignalFlags bits. - - - - - A mask for all #GSignalMatchType bits. - - - - - The signal accumulator is a special callback function that can be used -to collect return values of the various callbacks that are called -during a signal emission. The signal accumulator is specified at signal -creation time, if it is left %NULL, no accumulation of callback return -values is performed. The return value of signal emissions is then the -value returned by the last callback. - - - The accumulator function returns whether the signal emission - should be aborted. Returning %FALSE means to abort the - current emission and %TRUE is returned for continuation. - - - - - Signal invocation hint, see #GSignalInvocationHint. - - - - Accumulator to collect callback return values in, this - is the return value of the current signal emission. - - - - A #GValue holding the return value of the signal handler. - - - - Callback data that was specified when creating the signal. - - - - - - A simple function pointer to get invoked when the signal is emitted. This -allows you to tie a hook to the signal type, so that it will trap all -emissions of that signal, from any object. - -You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. - - - whether it wants to stay connected. If it returns %FALSE, the signal - hook is disconnected (and destroyed). - - - - - Signal invocation hint, see #GSignalInvocationHint. - - - - the number of parameters to the function, including - the instance on which the signal was emitted. - - - - the instance on which - the signal was emitted, followed by the parameters of the emission. - - - - - - user data associated with the hook. - - - - - - The signal flags are used to specify a signal's behaviour, the overall -signal description outlines how especially the RUN flags control the -stages of a signal emission. - - - Invoke the object method handler in the first emission stage. - - - Invoke the object method handler in the third emission stage. - - - Invoke the object method handler in the last emission stage. - - - Signals being emitted for an object while currently being in - emission for this very object will not be emitted recursively, - but instead cause the first emission to be restarted. - - - This signal supports "::detail" appendices to the signal name - upon handler connections and emissions. - - - Action signals are signals that may freely be emitted on alive - objects from user code via g_signal_emit() and friends, without - the need of being embedded into extra code that performs pre or - post emission adjustments on the object. They can also be thought - of as object methods which can be called generically by - third-party code. - - - No emissions hooks are supported for this signal. - - - Varargs signal emission will always collect the - arguments, even if there are no signal handlers connected. Since 2.30. - - - The signal is deprecated and will be removed - in a future version. A warning will be generated if it is connected while - running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. - - - - The #GSignalInvocationHint structure is used to pass on additional information -to callbacks during a signal emission. - - - The signal id of the signal invoking the callback - - - - The detail passed on for this emission - - - - The stage the signal emission is currently in, this - field will contain one of %G_SIGNAL_RUN_FIRST, - %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. - - - - - The match types specify what g_signal_handlers_block_matched(), -g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() -match signals by. - - - The signal id must be equal. - - - The signal detail must be equal. - - - The closure must be the same. - - - The C closure callback must be the same. - - - The closure data must be the same. - - - Only unblocked signals may be matched. - - - - A structure holding in-depth information for a specific signal. It is -filled in by the g_signal_query() function. - - - The signal id of the signal being queried, or 0 if the - signal to be queried was unknown. - - - - The signal name. - - - - The interface/instance type that this signal can be emitted for. - - - - The signal flags as passed in to g_signal_new(). - - - - The return type for user callbacks. - - - - The number of parameters that user callbacks take. - - - - The individual parameter types for - user callbacks, note that the effective callback signature is: - |[<!-- language="C" --> - @return_type callback (#gpointer data1, - [param_types param_names,] - gpointer data2); - ]| - - - - - - - Checks that @g_class is a class structure of the type identified by @g_type -and issues a warning if this is not the case. Returns @g_class casted -to a pointer to @c_type. %NULL is not a valid class structure. - -This macro should only be used in type implementations. - - - - Location of a #GTypeClass structure - - - The type to be returned - - - The corresponding C type of class structure of @g_type - - - - - Checks if @g_class is a class structure of the type identified by -@g_type. If @g_class is %NULL, %FALSE will be returned. - -This macro should only be used in type implementations. - - - - Location of a #GTypeClass structure - - - The type to be checked - - - - - Checks if @instance is a valid #GTypeInstance structure, -otherwise issues a warning and returns %FALSE. %NULL is not a valid -#GTypeInstance. - -This macro should only be used in type implementations. - - - - Location of a #GTypeInstance structure - - - - - Checks that @instance is an instance of the type identified by @g_type -and issues a warning if this is not the case. Returns @instance casted -to a pointer to @c_type. - -No warning will be issued if @instance is %NULL, and %NULL will be returned. - -This macro should only be used in type implementations. - - - - Location of a #GTypeInstance structure - - - The type to be returned - - - The corresponding C type of @g_type - - - - - Checks if @instance is an instance of the fundamental type identified by @g_type. -If @instance is %NULL, %FALSE will be returned. - -This macro should only be used in type implementations. - - - - Location of a #GTypeInstance structure. - - - The fundamental type to be checked - - - - - Checks if @instance is an instance of the type identified by @g_type. If -@instance is %NULL, %FALSE will be returned. - -This macro should only be used in type implementations. - - - - Location of a #GTypeInstance structure. - - - The type to be checked - - - - - Checks if @value has been initialized to hold values -of a value type. - -This macro should only be used in type implementations. - - - - a #GValue - - - - - Checks if @value has been initialized to hold values -of type @g_type. - -This macro should only be used in type implementations. - - - - a #GValue - - - The type to be checked - - - - - Gets the private class structure for a particular type. -The private structure must have been registered in the -get_type() function with g_type_add_class_private(). - -This macro should only be used in type implementations. - - - - the class of a type deriving from @private_type - - - the type identifying which private data to retrieve - - - The C type for the private structure - - - - - A bit in the type number that's supposed to be left untouched. - - - - - Get the type identifier from a given @class structure. - -This macro should only be used in type implementations. - - - - Location of a valid #GTypeClass structure - - - - - Get the type identifier from a given @instance structure. - -This macro should only be used in type implementations. - - - - Location of a valid #GTypeInstance structure - - - - - Get the type identifier from a given @interface structure. - -This macro should only be used in type implementations. - - - - Location of a valid #GTypeInterface structure - - - - - The fundamental type which is the ancestor of @type. -Fundamental types are types that serve as ultimate bases for the derived types, -thus they are the roots of distinct inheritance hierarchies. - - - - A #GType value. - - - - - An integer constant that represents the number of identifiers reserved -for types that are assigned at compile-time. - - - - - Shift value used in converting numbers to type IDs. - - - - - Checks if @type has a #GTypeValueTable. - - - - A #GType value - - - - - Get the class structure of a given @instance, casted -to a specified ancestor type @g_type of the instance. - -Note that while calling a GInstanceInitFunc(), the class pointer -gets modified, so it might not always return the expected pointer. - -This macro should only be used in type implementations. - - - - Location of the #GTypeInstance structure - - - The #GType of the class to be returned - - - The C type of the class structure - - - - - Get the interface structure for interface @g_type of a given @instance. - -This macro should only be used in type implementations. - - - - Location of the #GTypeInstance structure - - - The #GType of the interface to be returned - - - The C type of the interface structure - - - - - Gets the private structure for a particular type. -The private structure must have been registered in the -class_init function with g_type_class_add_private(). - -This macro should only be used in type implementations. - Use %G_ADD_PRIVATE and the generated - `your_type_get_instance_private()` function instead - - - - the instance of a type deriving from @private_type - - - the type identifying which private data to retrieve - - - The C type for the private structure - - - - - Checks if @type is an abstract type. An abstract type cannot be -instantiated and is normally used as an abstract base class for -derived classes. - - - - A #GType value - - - - - - - - - - - - Checks if @type is a classed type. - - - - A #GType value - - - - - Checks if @type is a deep derivable type. A deep derivable type -can be used as the base class of a deep (multi-level) class hierarchy. - - - - A #GType value - - - - - Checks if @type is a derivable type. A derivable type can -be used as the base class of a flat (single-level) class hierarchy. - - - - A #GType value - - - - - Checks if @type is derived (or in object-oriented terminology: -inherited) from another type (this holds true for all non-fundamental -types). - - - - A #GType value - - - - - Checks whether @type "is a" %G_TYPE_ENUM. - - - - a #GType ID. - - - - - Checks whether @type "is a" %G_TYPE_FLAGS. - - - - a #GType ID. - - - - - Checks if @type is a fundamental type. - - - - A #GType value - - - - - Checks if @type can be instantiated. Instantiation is the -process of creating an instance (object) of this type. - - - - A #GType value - - - - - Checks if @type is an interface type. -An interface type provides a pure API, the implementation -of which is provided by another type (which is then said to conform -to the interface). GLib interfaces are somewhat analogous to Java -interfaces and C++ classes containing only pure virtual functions, -with the difference that GType interfaces are not derivable (but see -g_type_interface_add_prerequisite() for an alternative). - - - - A #GType value - - - - - Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. - - - - Type id to check - - - - - Checks whether @type "is a" %G_TYPE_PARAM. - - - - a #GType ID - - - - - Checks whether the passed in type ID can be used for g_value_init(). -That is, this macro checks whether this type provides an implementation -of the #GTypeValueTable functions required for a type to create a #GValue of. - - - - A #GType value. - - - - - Checks if @type is an abstract value type. An abstract value type introduces -a value table, but can't be used for g_value_init() and is normally used as -an abstract base type for derived value types. - - - - A #GType value - - - - - Checks if @type is a value type and can be used with g_value_init(). - - - - A #GType value - - - - - Get the type ID for the fundamental type number @x. -Use g_type_fundamental_next() instead of this macro to create new fundamental -types. - - - - the fundamental type number. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - First fundamental type number to create a new fundamental type id with -G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. - - - - - Last fundamental type number reserved for BSE. - - - - - First fundamental type number to create a new fundamental type id with -G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. - - - - - Last fundamental type number reserved for GLib. - - - - - First available fundamental type number to create new fundamental -type id with G_TYPE_MAKE_FUNDAMENTAL(). - - - - - A callback function used for notification when the state -of a toggle reference changes. See g_object_add_toggle_ref(). - - - - - - - Callback data passed to g_object_add_toggle_ref() - - - - The object on which g_object_add_toggle_ref() was called. - - - - %TRUE if the toggle reference is now the - last reference to the object. %FALSE if the toggle - reference was the last reference and there are now other - references. - - - - - - - - - An opaque structure used as the base of all classes. - - - - - - Registers a private structure for an instantiatable type. - -When an object is allocated, the private structures for -the type and all of its parent types are allocated -sequentially in the same memory block as the public -structures, and are zero-filled. - -Note that the accumulated size of the private structures of -a type and all its parent types cannot exceed 64 KiB. - -This function should be called in the type's class_init() function. -The private structure can be retrieved using the -G_TYPE_INSTANCE_GET_PRIVATE() macro. - -The following example shows attaching a private structure -MyObjectPrivate to an object MyObject defined in the standard -GObject fashion in the type's class_init() function. - -Note the use of a structure member "priv" to avoid the overhead -of repeatedly calling MY_OBJECT_GET_PRIVATE(). - -|[<!-- language="C" --> -typedef struct _MyObject MyObject; -typedef struct _MyObjectPrivate MyObjectPrivate; - -struct _MyObject { - GObject parent; - - MyObjectPrivate *priv; -}; - -struct _MyObjectPrivate { - int some_field; -}; - -static void -my_object_class_init (MyObjectClass *klass) -{ - g_type_class_add_private (klass, sizeof (MyObjectPrivate)); -} - -static void -my_object_init (MyObject *my_object) -{ - my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, - MY_TYPE_OBJECT, - MyObjectPrivate); - // my_object->priv->some_field will be automatically initialised to 0 -} - -static int -my_object_get_some_field (MyObject *my_object) -{ - MyObjectPrivate *priv; - - g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); - - priv = my_object->priv; - - return priv->some_field; -} -]| - Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` - family of macros to add instance private data to a type - - - - - - - class structure for an instantiatable - type - - - - size of private structure - - - - - - Gets the offset of the private data for instances of @g_class. - -This is how many bytes you should add to the instance pointer of a -class in order to get the private data for the type represented by -@g_class. - -You can only call this function after you have registered a private -data area for @g_class using g_type_class_add_private(). - - - the offset, in bytes - - - - - a #GTypeClass - - - - - - - - - - - - - - - - - - - - This is a convenience function often needed in class initializers. -It returns the class structure of the immediate parent type of the -class passed in. Since derived classes hold a reference count on -their parent classes as long as they are instantiated, the returned -class will always exist. - -This function is essentially equivalent to: -g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) - - - the parent class - of @g_class - - - - - the #GTypeClass structure to - retrieve the parent class for - - - - - - Decrements the reference count of the class structure being passed in. -Once the last reference count of a class has been released, classes -may be finalized by the type system, so further dereferencing of a -class pointer after g_type_class_unref() are invalid. - - - - - - - a #GTypeClass structure to unref - - - - - - A variant of g_type_class_unref() for use in #GTypeClassCacheFunc -implementations. It unreferences a class without consulting the chain -of #GTypeClassCacheFuncs, avoiding the recursion which would occur -otherwise. - - - - - - - a #GTypeClass structure to unref - - - - - - - - - - - - - - - - - - - - This function is essentially the same as g_type_class_ref(), -except that the classes reference count isn't incremented. -As a consequence, this function may return %NULL if the class -of the type passed in does not currently exist (hasn't been -referenced before). - - - the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist - - - - - type ID of a classed type - - - - - - A more efficient version of g_type_class_peek() which works only for -static types. - - - the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist or is dynamically loaded - - - - - type ID of a classed type - - - - - - Increments the reference count of the class structure belonging to -@type. This function will demand-create the class if it doesn't -exist already. - - - the #GTypeClass - structure for the given type ID - - - - - type ID of a classed type - - - - - - - A callback function which is called when the reference count of a class -drops to zero. It may use g_type_class_ref() to prevent the class from -being freed. You should not call g_type_class_unref() from a -#GTypeClassCacheFunc function to prevent infinite recursion, use -g_type_class_unref_uncached() instead. - -The functions have to check the class id passed in to figure -whether they actually want to cache the class of this type, since all -classes are routed through the same #GTypeClassCacheFunc chain. - - - %TRUE to stop further #GTypeClassCacheFuncs from being - called, %FALSE to continue - - - - - data that was given to the g_type_add_class_cache_func() call - - - - The #GTypeClass structure which is - unreferenced - - - - - - These flags used to be passed to g_type_init_with_debug_flags() which -is now deprecated. - -If you need to enable debugging features, use the GOBJECT_DEBUG -environment variable. - g_type_init() is now done automatically - - - Print no messages - - - Print messages about object bookkeeping - - - Print messages about signal emissions - - - Keep a count of instances of each type - - - Mask covering all debug flags - - - - Bit masks used to check or determine characteristics of a type. - - - Indicates an abstract type. No instances can be - created for an abstract type - - - Indicates an abstract value type, i.e. a type - that introduces a value table, but can't be used for - g_value_init() - - - - Bit masks used to check or determine specific characteristics of a -fundamental type. - - - Indicates a classed type - - - Indicates an instantiable type (implies classed) - - - Indicates a flat derivable type - - - Indicates a deep derivable type (implies derivable) - - - - A structure that provides information to the type system which is -used specifically for managing fundamental types. - - - #GTypeFundamentalFlags describing the characteristics of the fundamental type - - - - - This structure is used to provide the type system with the information -required to initialize and destruct (finalize) a type's class and -its instances. - -The initialized structure is passed to the g_type_register_static() function -(or is copied into the provided #GTypeInfo structure in the -g_type_plugin_complete_type_info()). The type system will perform a deep -copy of this structure, so its memory does not need to be persistent -across invocation of g_type_register_static(). - - - Size of the class structure (required for interface, classed and instantiatable types) - - - - Location of the base initialization function (optional) - - - - Location of the base finalization function (optional) - - - - Location of the class initialization function for - classed and instantiatable types. Location of the default vtable - inititalization function for interface types. (optional) This function - is used both to fill in virtual functions in the class or default vtable, - and to do type-specific setup such as registering signals and object - properties. - - - - Location of the class finalization function for - classed and instantiatable types. Location of the default vtable - finalization function for interface types. (optional) - - - - User-supplied data passed to the class init/finalize functions - - - - Size of the instance (object) structure (required for instantiatable types only) - - - - Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. - - - - Location of the instance initialization function (optional, for instantiatable types only) - - - - A #GTypeValueTable function table for generic handling of GValues - of this type (usually only useful for fundamental types) - - - - - An opaque structure used as the base of all type instances. - - - - - - - - - - - - - - - - - - - - - An opaque structure used as the base of all interface types. - - - - - - - - - Returns the corresponding #GTypeInterface structure of the parent type -of the instance type to which @g_iface belongs. This is useful when -deriving the implementation of an interface from the parent type and -then possibly overriding some methods. - - - the - corresponding #GTypeInterface structure of the parent type of the - instance type to which @g_iface belongs, or %NULL if the parent - type doesn't conform to the interface - - - - - a #GTypeInterface structure - - - - - - Adds @prerequisite_type to the list of prerequisites of @interface_type. -This means that any type implementing @interface_type must also implement -@prerequisite_type. Prerequisites can be thought of as an alternative to -interface derivation (which GType doesn't support). An interface can have -at most one instantiatable prerequisite type. - - - - - - - #GType value of an interface type - - - - #GType value of an interface or instantiatable type - - - - - - Returns the #GTypePlugin structure for the dynamic interface -@interface_type which has been added to @instance_type, or %NULL -if @interface_type has not been added to @instance_type or does -not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - - - the #GTypePlugin for the dynamic - interface @interface_type of @instance_type - - - - - #GType of an instantiatable type - - - - #GType of an interface type - - - - - - Returns the #GTypeInterface structure of an interface to which the -passed in class conforms. - - - the #GTypeInterface - structure of @iface_type if implemented by @instance_class, %NULL - otherwise - - - - - a #GTypeClass structure - - - - an interface ID which this class conforms to - - - - - - Returns the prerequisites of an interfaces type. - - - a - newly-allocated zero-terminated array of #GType containing - the prerequisites of @interface_type - - - - - - - an interface type - - - - location to return the number - of prerequisites, or %NULL - - - - - - - A callback called after an interface vtable is initialized. -See g_type_add_interface_check(). - - - - - - - data passed to g_type_add_interface_check() - - - - the interface that has been - initialized - - - - - - #GTypeModule provides a simple implementation of the #GTypePlugin -interface. The model of #GTypeModule is a dynamically loaded module -which implements some number of types and interface implementations. -When the module is loaded, it registers its types and interfaces -using g_type_module_register_type() and g_type_module_add_interface(). -As long as any instances of these types and interface implementations -are in use, the module is kept loaded. When the types and interfaces -are gone, the module may be unloaded. If the types and interfaces -become used again, the module will be reloaded. Note that the last -unref cannot happen in module code, since that would lead to the -caller's code being unloaded before g_object_unref() returns to it. - -Keeping track of whether the module should be loaded or not is done by -using a use count - it starts at zero, and whenever it is greater than -zero, the module is loaded. The use count is maintained internally by -the type system, but also can be explicitly controlled by -g_type_module_use() and g_type_module_unuse(). Typically, when loading -a module for the first type, g_type_module_use() will be used to load -it so that it can initialize its types. At some later point, when the -module no longer needs to be loaded except for the type -implementations it contains, g_type_module_unuse() is called. - -#GTypeModule does not actually provide any implementation of module -loading and unloading. To create a particular module type you must -derive from #GTypeModule and implement the load and unload functions -in #GTypeModuleClass. - - - - - - - - - - - - - - - - - - - - - - - - - - Registers an additional interface for a type, whose interface lives -in the given type plugin. If the interface was already registered -for the type in this plugin, nothing will be done. - -As long as any instances of the type exist, the type plugin will -not be unloaded. - -Since 2.56 if @module is %NULL this will call g_type_add_interface_static() -instead. This can be used when making a static build of the module. - - - - - - - a #GTypeModule - - - - type to which to add the interface. - - - - interface type to add - - - - type information structure - - - - - - Looks up or registers an enumeration that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - -As long as any instances of the type exist, the type plugin will -not be unloaded. - -Since 2.56 if @module is %NULL this will call g_type_register_static() -instead. This can be used when making a static build of the module. - - - the new or existing type ID - - - - - a #GTypeModule - - - - name for the type - - - - an array of #GEnumValue structs for the - possible enumeration values. The array is - terminated by a struct with all members being - 0. - - - - - - Looks up or registers a flags type that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - -As long as any instances of the type exist, the type plugin will -not be unloaded. - -Since 2.56 if @module is %NULL this will call g_type_register_static() -instead. This can be used when making a static build of the module. - - - the new or existing type ID - - - - - a #GTypeModule - - - - name for the type - - - - an array of #GFlagsValue structs for the - possible flags values. The array is - terminated by a struct with all members being - 0. - - - - - - Looks up or registers a type that is implemented with a particular -type plugin. If a type with name @type_name was previously registered, -the #GType identifier for the type is returned, otherwise the type -is newly registered, and the resulting #GType identifier returned. - -When reregistering a type (typically because a module is unloaded -then reloaded, and reinitialized), @module and @parent_type must -be the same as they were previously. - -As long as any instances of the type exist, the type plugin will -not be unloaded. - -Since 2.56 if @module is %NULL this will call g_type_register_static() -instead. This can be used when making a static build of the module. - - - the new or existing type ID - - - - - a #GTypeModule - - - - the type for the parent class - - - - name for the type - - - - type information structure - - - - flags field providing details about the type - - - - - - Sets the name for a #GTypeModule - - - - - - - a #GTypeModule. - - - - a human-readable name to use in error messages. - - - - - - Decreases the use count of a #GTypeModule by one. If the -result is zero, the module will be unloaded. (However, the -#GTypeModule will not be freed, and types associated with the -#GTypeModule are not unregistered. Once a #GTypeModule is -initialized, it must exist forever.) - - - - - - - a #GTypeModule - - - - - - Increases the use count of a #GTypeModule by one. If the -use count was zero before, the plugin will be loaded. -If loading the plugin fails, the use count is reset to -its prior value. - - - %FALSE if the plugin needed to be loaded and - loading the plugin failed. - - - - - a #GTypeModule - - - - - - - - - - - - - - - - - - - - - - the name of the module - - - - - In order to implement dynamic loading of types based on #GTypeModule, -the @load and @unload functions in #GTypeModuleClass must be implemented. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The GObject type system supports dynamic loading of types. -The #GTypePlugin interface is used to handle the lifecycle -of dynamically loaded types. It goes as follows: - -1. The type is initially introduced (usually upon loading the module - the first time, or by your main application that knows what modules - introduces what types), like this: - |[<!-- language="C" --> - new_type_id = g_type_register_dynamic (parent_type_id, - "TypeName", - new_type_plugin, - type_flags); - ]| - where @new_type_plugin is an implementation of the - #GTypePlugin interface. - -2. The type's implementation is referenced, e.g. through - g_type_class_ref() or through g_type_create_instance() (this is - being called by g_object_new()) or through one of the above done on - a type derived from @new_type_id. - -3. This causes the type system to load the type's implementation by - calling g_type_plugin_use() and g_type_plugin_complete_type_info() - on @new_type_plugin. - -4. At some point the type's implementation isn't required anymore, - e.g. after g_type_class_unref() or g_type_free_instance() (called - when the reference count of an instance drops to zero). - -5. This causes the type system to throw away the information retrieved - from g_type_plugin_complete_type_info() and then it calls - g_type_plugin_unuse() on @new_type_plugin. - -6. Things may repeat from the second step. - -So basically, you need to implement a #GTypePlugin type that -carries a use_count, once use_count goes from zero to one, you need -to load the implementation to successfully handle the upcoming -g_type_plugin_complete_type_info() call. Later, maybe after -succeeding use/unuse calls, once use_count drops to zero, you can -unload the implementation again. The type system makes sure to call -g_type_plugin_use() and g_type_plugin_complete_type_info() again -when the type is needed again. - -#GTypeModule is an implementation of #GTypePlugin that already -implements most of this except for the actual module loading and -unloading. It even handles multiple registered types per module. - - Calls the @complete_interface_info function from the -#GTypePluginClass of @plugin. There should be no need to use this -function outside of the GObject type system itself. - - - - - - - the #GTypePlugin - - - - the #GType of an instantiable type to which the interface - is added - - - - the #GType of the interface whose info is completed - - - - the #GInterfaceInfo to fill in - - - - - - Calls the @complete_type_info function from the #GTypePluginClass of @plugin. -There should be no need to use this function outside of the GObject -type system itself. - - - - - - - a #GTypePlugin - - - - the #GType whose info is completed - - - - the #GTypeInfo struct to fill in - - - - the #GTypeValueTable to fill in - - - - - - Calls the @unuse_plugin function from the #GTypePluginClass of -@plugin. There should be no need to use this function outside of -the GObject type system itself. - - - - - - - a #GTypePlugin - - - - - - Calls the @use_plugin function from the #GTypePluginClass of -@plugin. There should be no need to use this function outside of -the GObject type system itself. - - - - - - - a #GTypePlugin - - - - - - - The #GTypePlugin interface is used by the type system in order to handle -the lifecycle of dynamically loaded types. - - - - - - Increases the use count of the plugin. - - - - Decreases the use count of the plugin. - - - - Fills in the #GTypeInfo and - #GTypeValueTable structs for the type. The structs are initialized - with `memset(s, 0, sizeof (s))` before calling this function. - - - - Fills in missing parts of the #GInterfaceInfo - for the interface. The structs is initialized with - `memset(s, 0, sizeof (s))` before calling this function. - - - - - The type of the @complete_interface_info function of #GTypePluginClass. - - - - - - - the #GTypePlugin - - - - the #GType of an instantiable type to which the interface - is added - - - - the #GType of the interface whose info is completed - - - - the #GInterfaceInfo to fill in - - - - - - The type of the @complete_type_info function of #GTypePluginClass. - - - - - - - the #GTypePlugin - - - - the #GType whose info is completed - - - - the #GTypeInfo struct to fill in - - - - the #GTypeValueTable to fill in - - - - - - The type of the @unuse_plugin function of #GTypePluginClass. - - - - - - - the #GTypePlugin whose use count should be decreased - - - - - - The type of the @use_plugin function of #GTypePluginClass, which gets called -to increase the use count of @plugin. - - - - - - - the #GTypePlugin whose use count should be increased - - - - - - A structure holding information for a specific type. -It is filled in by the g_type_query() function. - - - the #GType value of the type - - - - the name of the type - - - - the size of the class structure - - - - the size of the instance structure - - - - - The #GTypeValueTable provides the functions required by the #GValue -implementation, to serve as a container for values of a type. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A string format describing how to collect the contents of - this value bit-by-bit. Each character in the format represents - an argument to be collected, and the characters themselves indicate - the type of the argument. Currently supported arguments are: - - 'i' - Integers. passed as collect_values[].v_int. - - 'l' - Longs. passed as collect_values[].v_long. - - 'd' - Doubles. passed as collect_values[].v_double. - - 'p' - Pointers. passed as collect_values[].v_pointer. - It should be noted that for variable argument list construction, - ANSI C promotes every type smaller than an integer to an int, and - floats to doubles. So for collection of short int or char, 'i' - needs to be used, and for collection of floats 'd'. - - - - - - - - - - - - - - - - - - - - - - - - - - Format description of the arguments to collect for @lcopy_value, - analogous to @collect_format. Usually, @lcopy_format string consists - only of 'p's to provide lcopy_value() with pointers to storage locations. - - - - - - - - - - - - - - - - - - - - - - - - - - Returns the location of the #GTypeValueTable associated with @type. - -Note that this function should only be used from source code -that implements or has internal knowledge of the implementation of -@type. - - - location of the #GTypeValueTable associated with @type or - %NULL if there is no #GTypeValueTable associated with @type - - - - - a #GType - - - - - - - Checks if @value holds (or contains) a value of @type. -This macro will also check for @value != %NULL and issue a -warning if the check fails. - - - - A #GValue structure. - - - A #GType value. - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values derived -from type %G_TYPE_BOXED. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_INT. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_INT64. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_LONG. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_STRING. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_UINT. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. - - - - a valid #GValue structure - - - - - Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. - - - - a valid #GValue structure - - - - - If passed to G_VALUE_COLLECT(), allocated data won't be copied -but used verbatim. This does not affect ref-counted types like -objects. - - - - - Get the type identifier of @value. - - - - A #GValue structure. - - - - - Gets the type name of @value. - - - - A #GValue structure. - - - - - This is the signature of va_list marshaller functions, an optional -marshaller that can be used in some situations to avoid -marshalling the signal argument into GValues. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue to store the return - value. May be %NULL if the callback of @closure doesn't return a - value. - - - - the instance on which the closure is - invoked. - - - - va_list of arguments to be passed to the closure. - - - - additional data specified when - registering the marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - the length of the @param_types array - - - - the #GType of each argument from - @args. - - - - - - - - An opaque structure used to hold different types of values. -The data within the structure has protected scope: it is accessible only -to functions within a #GTypeValueTable structure, or implementations of -the g_value_*() API. That is, code portions which implement new fundamental -types. -#GValue users cannot make any assumptions about how data is stored -within the 2 element @data union, and the @g_type member should -only be accessed through the G_VALUE_TYPE() macro. - - - - - - - - - - - Copies the value of @src_value into @dest_value. - - - - - - - An initialized #GValue structure. - - - - An initialized #GValue structure of the same type as @src_value. - - - - - - Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, -the boxed value is duplicated and needs to be later freed with -g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), -return_value); - - - boxed contents of @value - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - - - Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing -its reference count. If the contents of the #GValue are %NULL, then -%NULL will be returned. - - - object content of @value, - should be unreferenced when no longer needed. - - - - - a valid #GValue whose type is derived from %G_TYPE_OBJECT - - - - - - Get the contents of a %G_TYPE_PARAM #GValue, increasing its -reference count. - - - #GParamSpec content of @value, should be unreferenced when - no longer needed. - - - - - a valid #GValue whose type is derived from %G_TYPE_PARAM - - - - - - Get a copy the contents of a %G_TYPE_STRING #GValue. - - - a newly allocated copy of the string content of @value - - - - - a valid #GValue of type %G_TYPE_STRING - - - - - - Get the contents of a variant #GValue, increasing its refcount. The returned -#GVariant is never floating. - - - variant contents of @value (may be %NULL); - should be unreffed using g_variant_unref() when no longer needed - - - - - a valid #GValue of type %G_TYPE_VARIANT - - - - - - Determines if @value will fit inside the size of a pointer value. -This is an internal function introduced mainly for C marshallers. - - - %TRUE if @value will fit inside a pointer value. - - - - - An initialized #GValue structure. - - - - - - Get the contents of a %G_TYPE_BOOLEAN #GValue. - - - boolean contents of @value - - - - - a valid #GValue of type %G_TYPE_BOOLEAN - - - - - - Get the contents of a %G_TYPE_BOXED derived #GValue. - - - boxed contents of @value - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - - - Do not use this function; it is broken on platforms where the %char -type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). - -Get the contents of a %G_TYPE_CHAR #GValue. - This function's return type is broken, see g_value_get_schar() - - - character contents of @value - - - - - a valid #GValue of type %G_TYPE_CHAR - - - - - - Get the contents of a %G_TYPE_DOUBLE #GValue. - - - double contents of @value - - - - - a valid #GValue of type %G_TYPE_DOUBLE - - - - - - Get the contents of a %G_TYPE_ENUM #GValue. - - - enum contents of @value - - - - - a valid #GValue whose type is derived from %G_TYPE_ENUM - - - - - - Get the contents of a %G_TYPE_FLAGS #GValue. - - - flags contents of @value - - - - - a valid #GValue whose type is derived from %G_TYPE_FLAGS - - - - - - Get the contents of a %G_TYPE_FLOAT #GValue. - - - float contents of @value - - - - - a valid #GValue of type %G_TYPE_FLOAT - - - - - - Get the contents of a %G_TYPE_GTYPE #GValue. - - - the #GType stored in @value - - - - - a valid #GValue of type %G_TYPE_GTYPE - - - - - - Get the contents of a %G_TYPE_INT #GValue. - - - integer contents of @value - - - - - a valid #GValue of type %G_TYPE_INT - - - - - - Get the contents of a %G_TYPE_INT64 #GValue. - - - 64bit integer contents of @value - - - - - a valid #GValue of type %G_TYPE_INT64 - - - - - - Get the contents of a %G_TYPE_LONG #GValue. - - - long integer contents of @value - - - - - a valid #GValue of type %G_TYPE_LONG - - - - - - Get the contents of a %G_TYPE_OBJECT derived #GValue. - - - object contents of @value - - - - - a valid #GValue of %G_TYPE_OBJECT derived type - - - - - - Get the contents of a %G_TYPE_PARAM #GValue. - - - #GParamSpec content of @value - - - - - a valid #GValue whose type is derived from %G_TYPE_PARAM - - - - - - Get the contents of a pointer #GValue. - - - pointer contents of @value - - - - - a valid #GValue of %G_TYPE_POINTER - - - - - - Get the contents of a %G_TYPE_CHAR #GValue. - - - signed 8 bit integer contents of @value - - - - - a valid #GValue of type %G_TYPE_CHAR - - - - - - Get the contents of a %G_TYPE_STRING #GValue. - - - string content of @value - - - - - a valid #GValue of type %G_TYPE_STRING - - - - - - Get the contents of a %G_TYPE_UCHAR #GValue. - - - unsigned character contents of @value - - - - - a valid #GValue of type %G_TYPE_UCHAR - - - - - - Get the contents of a %G_TYPE_UINT #GValue. - - - unsigned integer contents of @value - - - - - a valid #GValue of type %G_TYPE_UINT - - - - - - Get the contents of a %G_TYPE_UINT64 #GValue. - - - unsigned 64bit integer contents of @value - - - - - a valid #GValue of type %G_TYPE_UINT64 - - - - - - Get the contents of a %G_TYPE_ULONG #GValue. - - - unsigned long integer contents of @value - - - - - a valid #GValue of type %G_TYPE_ULONG - - - - - - Get the contents of a variant #GValue. - - - variant contents of @value (may be %NULL) - - - - - a valid #GValue of type %G_TYPE_VARIANT - - - - - - Initializes @value with the default value of @type. - - - the #GValue structure that has been passed in - - - - - A zero-filled (uninitialized) #GValue structure. - - - - Type the #GValue should hold values of. - - - - - - Initializes and sets @value from an instantiatable type via the -value_table's collect_value() function. - -Note: The @value will be initialised with the exact type of -@instance. If you wish to set the @value's type to a different GType -(such as a parent class GType), you need to manually call -g_value_init() and g_value_set_instance(). - - - - - - - An uninitialized #GValue structure. - - - - the instance - - - - - - Returns the value contents as pointer. This function asserts that -g_value_fits_pointer() returned %TRUE for the passed in value. -This is an internal function introduced mainly for C marshallers. - - - the value contents as pointer - - - - - An initialized #GValue structure - - - - - - Clears the current value in @value and resets it to the default value -(as if the value had just been initialized). - - - the #GValue structure that has been passed in - - - - - An initialized #GValue structure. - - - - - - Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. - - - - - - - a valid #GValue of type %G_TYPE_BOOLEAN - - - - boolean value to be set - - - - - - Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. - - - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - boxed value to be set - - - - - - This is an internal function introduced mainly for C marshallers. - Use g_value_take_boxed() instead. - - - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - duplicated unowned boxed value to be set - - - - - - Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - This function's input type is broken, see g_value_set_schar() - - - - - - - a valid #GValue of type %G_TYPE_CHAR - - - - character value to be set - - - - - - Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. - - - - - - - a valid #GValue of type %G_TYPE_DOUBLE - - - - double value to be set - - - - - - Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. - - - - - - - a valid #GValue whose type is derived from %G_TYPE_ENUM - - - - enum value to be set - - - - - - Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. - - - - - - - a valid #GValue whose type is derived from %G_TYPE_FLAGS - - - - flags value to be set - - - - - - Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. - - - - - - - a valid #GValue of type %G_TYPE_FLOAT - - - - float value to be set - - - - - - Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. - - - - - - - a valid #GValue of type %G_TYPE_GTYPE - - - - #GType to be set - - - - - - Sets @value from an instantiatable type via the -value_table's collect_value() function. - - - - - - - An initialized #GValue structure. - - - - the instance - - - - - - Set the contents of a %G_TYPE_INT #GValue to @v_int. - - - - - - - a valid #GValue of type %G_TYPE_INT - - - - integer value to be set - - - - - - Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. - - - - - - - a valid #GValue of type %G_TYPE_INT64 - - - - 64bit integer value to be set - - - - - - Set the contents of a %G_TYPE_LONG #GValue to @v_long. - - - - - - - a valid #GValue of type %G_TYPE_LONG - - - - long integer value to be set - - - - - - Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. - -g_value_set_object() increases the reference count of @v_object -(the #GValue holds a reference to @v_object). If you do not wish -to increase the reference count of the object (i.e. you wish to -pass your current reference to the #GValue because you no longer -need it), use g_value_take_object() instead. - -It is important that your #GValue holds a reference to @v_object (either its -own, or one it has taken) to ensure that the object won't be destroyed while -the #GValue still exists). - - - - - - - a valid #GValue of %G_TYPE_OBJECT derived type - - - - object value to be set - - - - - - This is an internal function introduced mainly for C marshallers. - Use g_value_take_object() instead. - - - - - - - a valid #GValue of %G_TYPE_OBJECT derived type - - - - object value to be set - - - - - - Set the contents of a %G_TYPE_PARAM #GValue to @param. - - - - - - - a valid #GValue of type %G_TYPE_PARAM - - - - the #GParamSpec to be set - - - - - - This is an internal function introduced mainly for C marshallers. - Use g_value_take_param() instead. - - - - - - - a valid #GValue of type %G_TYPE_PARAM - - - - the #GParamSpec to be set - - - - - - Set the contents of a pointer #GValue to @v_pointer. - - - - - - - a valid #GValue of %G_TYPE_POINTER - - - - pointer value to be set - - - - - - Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - - - - - - - a valid #GValue of type %G_TYPE_CHAR - - - - signed 8 bit integer to be set - - - - - - Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. -The boxed value is assumed to be static, and is thus not duplicated -when setting the #GValue. - - - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - static boxed value to be set - - - - - - Set the contents of a %G_TYPE_STRING #GValue to @v_string. -The string is assumed to be static, and is thus not duplicated -when setting the #GValue. - - - - - - - a valid #GValue of type %G_TYPE_STRING - - - - static string to be set - - - - - - Set the contents of a %G_TYPE_STRING #GValue to @v_string. - - - - - - - a valid #GValue of type %G_TYPE_STRING - - - - caller-owned string to be duplicated for the #GValue - - - - - - This is an internal function introduced mainly for C marshallers. - Use g_value_take_string() instead. - - - - - - - a valid #GValue of type %G_TYPE_STRING - - - - duplicated unowned string to be set - - - - - - Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. - - - - - - - a valid #GValue of type %G_TYPE_UCHAR - - - - unsigned character value to be set - - - - - - Set the contents of a %G_TYPE_UINT #GValue to @v_uint. - - - - - - - a valid #GValue of type %G_TYPE_UINT - - - - unsigned integer value to be set - - - - - - Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. - - - - - - - a valid #GValue of type %G_TYPE_UINT64 - - - - unsigned 64bit integer value to be set - - - - - - Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. - - - - - - - a valid #GValue of type %G_TYPE_ULONG - - - - unsigned long integer value to be set - - - - - - Set the contents of a variant #GValue to @variant. -If the variant is floating, it is consumed. - - - - - - - a valid #GValue of type %G_TYPE_VARIANT - - - - a #GVariant, or %NULL - - - - - - Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed -and takes over the ownership of the caller’s reference to @v_boxed; -the caller doesn’t have to unref it any more. - - - - - - - a valid #GValue of %G_TYPE_BOXED derived type - - - - duplicated unowned boxed value to be set - - - - - - Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object -and takes over the ownership of the caller’s reference to @v_object; -the caller doesn’t have to unref it any more (i.e. the reference -count of the object is not increased). - -If you want the #GValue to hold its own reference to @v_object, use -g_value_set_object() instead. - - - - - - - a valid #GValue of %G_TYPE_OBJECT derived type - - - - object value to be set - - - - - - Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes -over the ownership of the caller’s reference to @param; the caller -doesn’t have to unref it any more. - - - - - - - a valid #GValue of type %G_TYPE_PARAM - - - - the #GParamSpec to be set - - - - - - Sets the contents of a %G_TYPE_STRING #GValue to @v_string. - - - - - - - a valid #GValue of type %G_TYPE_STRING - - - - string to take ownership of - - - - - - Set the contents of a variant #GValue to @variant, and takes over -the ownership of the caller's reference to @variant; -the caller doesn't have to unref it any more (i.e. the reference -count of the variant is not increased). - -If @variant was floating then its floating reference is converted to -a hard reference. - -If you want the #GValue to hold its own reference to @variant, use -g_value_set_variant() instead. - -This is an internal function introduced mainly for C marshallers. - - - - - - - a valid #GValue of type %G_TYPE_VARIANT - - - - a #GVariant, or %NULL - - - - - - Tries to cast the contents of @src_value into a type appropriate -to store in @dest_value, e.g. to transform a %G_TYPE_INT value -into a %G_TYPE_FLOAT value. Performing transformations between -value types might incur precision lossage. Especially -transformations into strings might reveal seemingly arbitrary -results and shouldn't be relied upon for production code (such -as rcfile value or object property serialization). - - - Whether a transformation rule was found and could be applied. - Upon failing transformations, @dest_value is left untouched. - - - - - Source value. - - - - Target value. - - - - - - Clears the current value in @value (if any) and "unsets" the type, -this releases all resources associated with this GValue. An unset -value is the same as an uninitialized (zero-filled) #GValue -structure. - - - - - - - An initialized #GValue structure. - - - - - - Registers a value transformation function for use in g_value_transform(). -A previously registered transformation function for @src_type and @dest_type -will be replaced. - - - - - - - Source type. - - - - Target type. - - - - a function which transforms values of type @src_type - into value of type @dest_type - - - - - - Returns whether a #GValue of type @src_type can be copied into -a #GValue of type @dest_type. - - - %TRUE if g_value_copy() is possible with @src_type and @dest_type. - - - - - source type to be copied. - - - - destination type for copying. - - - - - - Check whether g_value_transform() is able to transform values -of type @src_type into values of type @dest_type. Note that for -the types to be transformable, they must be compatible or a -transformation function must be registered. - - - %TRUE if the transformation is possible, %FALSE otherwise. - - - - - Source type. - - - - Target type. - - - - - - - A #GValueArray contains an array of #GValue elements. - - - number of values contained in the array - - - - array of values - - - - - - - Allocate and initialize a new #GValueArray, optionally preserve space -for @n_prealloced elements. New arrays always contain 0 elements, -regardless of the value of @n_prealloced. - Use #GArray and g_array_sized_new() instead. - - - a newly allocated #GValueArray with 0 values - - - - - number of values to preallocate space for - - - - - - Insert a copy of @value as last element of @value_array. If @value is -%NULL, an uninitialized value is appended. - Use #GArray and g_array_append_val() instead. - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to add an element to - - - - #GValue to copy into #GValueArray, or %NULL - - - - - - Construct an exact copy of a #GValueArray by duplicating all its -contents. - Use #GArray and g_array_ref() instead. - - - Newly allocated copy of #GValueArray - - - - - #GValueArray to copy - - - - - - Free a #GValueArray including its contents. - Use #GArray and g_array_unref() instead. - - - - - - - #GValueArray to free - - - - - - Return a pointer to the value at @index_ containd in @value_array. - Use g_array_index() instead. - - - pointer to a value at @index_ in @value_array - - - - - #GValueArray to get a value from - - - - index of the value of interest - - - - - - Insert a copy of @value at specified position into @value_array. If @value -is %NULL, an uninitialized value is inserted. - Use #GArray and g_array_insert_val() instead. - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to add an element to - - - - insertion position, must be <= value_array->;n_values - - - - #GValue to copy into #GValueArray, or %NULL - - - - - - Insert a copy of @value as first element of @value_array. If @value is -%NULL, an uninitialized value is prepended. - Use #GArray and g_array_prepend_val() instead. - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to add an element to - - - - #GValue to copy into #GValueArray, or %NULL - - - - - - Remove the value at position @index_ from @value_array. - Use #GArray and g_array_remove_index() instead. - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to remove an element from - - - - position of value to remove, which must be less than - @value_array->n_values - - - - - - Sort @value_array using @compare_func to compare the elements according to -the semantics of #GCompareFunc. - -The current implementation uses the same sorting algorithm as standard -C qsort() function. - Use #GArray and g_array_sort(). - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to sort - - - - function to compare elements - - - - - - Sort @value_array using @compare_func to compare the elements according -to the semantics of #GCompareDataFunc. - -The current implementation uses the same sorting algorithm as standard -C qsort() function. - Use #GArray and g_array_sort_with_data(). - - - the #GValueArray passed in as @value_array - - - - - #GValueArray to sort - - - - function to compare elements - - - - extra data argument provided for @compare_func - - - - - - - The type of value transformation functions which can be registered with -g_value_register_transform_func(). - -@dest_value will be initialized to the correct destination type. - - - - - - - Source value. - - - - Target value. - - - - - - A #GWeakNotify function can be added to an object as a callback that gets -triggered when the object is finalized. Since the object is already being -finalized when the #GWeakNotify is called, there's not much you could do -with the object, apart from e.g. using its address as hash-index or the like. - - - - - - - data that was provided when the weak reference was established - - - - the object being finalized - - - - - - A structure containing a weak reference to a #GObject. It can either -be empty (i.e. point to %NULL), or point to an object for as long as -at least one "strong" reference to that object exists. Before the -object's #GObjectClass.dispose method is called, every #GWeakRef -associated with becomes empty (i.e. points to %NULL). - -Like #GValue, #GWeakRef can be statically allocated, stack- or -heap-allocated, or embedded in larger structures. - -Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak -reference is thread-safe: converting a weak pointer to a reference is -atomic with respect to invalidation of weak pointers to destroyed -objects. - -If the object's #GObjectClass.dispose method results in additional -references to the object being held, any #GWeakRefs taken -before it was disposed will continue to point to %NULL. If -#GWeakRefs are taken after the object is disposed and -re-referenced, they will continue to point to it until its refcount -goes back to zero, at which point they too will be invalidated. - - - - - - - - - Frees resources associated with a non-statically-allocated #GWeakRef. -After this call, the #GWeakRef is left in an undefined state. - -You should only call this on a #GWeakRef that previously had -g_weak_ref_init() called on it. - - - - - - - location of a weak reference, which - may be empty - - - - - - If @weak_ref is not empty, atomically acquire a strong -reference to the object it points to, and return that reference. - -This function is needed because of the potential race between taking -the pointer value and g_object_ref() on it, if the object was losing -its last reference at the same time in a different thread. - -The caller should release the resulting reference in the usual way, -by using g_object_unref(). - - - the object pointed to - by @weak_ref, or %NULL if it was empty - - - - - location of a weak reference to a #GObject - - - - - - Initialise a non-statically-allocated #GWeakRef. - -This function also calls g_weak_ref_set() with @object on the -freshly-initialised weak reference. - -This function should always be matched with a call to -g_weak_ref_clear(). It is not necessary to use this function for a -#GWeakRef in static storage because it will already be -properly initialised. Just use g_weak_ref_set() directly. - - - - - - - uninitialized or empty location for a weak - reference - - - - a #GObject or %NULL - - - - - - Change the object to which @weak_ref points, or set it to -%NULL. - -You must own a strong reference on @object while calling this -function. - - - - - - - location for a weak reference - - - - a #GObject or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Assert that @object is non-%NULL, then release one reference to it with -g_object_unref() and assert that it has been finalized (i.e. that there -are no more references). - -If assertions are disabled via `G_DISABLE_ASSERT`, -this macro just calls g_object_unref() without any further checks. - -This macro should only be used in regression tests. - - - - an object - - - - - Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. - - - The newly created copy of the boxed - structure. - - - - - The type of @src_boxed. - - - - The boxed structure to be copied. - - - - - - Free the boxed structure @boxed which is of type @boxed_type. - - - - - - - The type of @boxed. - - - - The boxed structure to be freed. - - - - - - This function creates a new %G_TYPE_BOXED derived type id for a new -boxed type with name @name. Boxed type handling functions have to be -provided to copy and free opaque boxed structures of this type. - - - New %G_TYPE_BOXED derived type id for @name. - - - - - Name of the new boxed type. - - - - Boxed structure copy function. - - - - Boxed structure free function. - - - - - - A #GClosureMarshal function for use with signals with handlers that -take two boxed pointers as arguments and return a boolean. If you -have such a signal, you will probably also need to use an -accumulator, such as g_signal_accumulator_true_handled(). - - - - - - - A #GClosure. - - - - A #GValue to store the return value. May be %NULL - if the callback of closure doesn't return a value. - - - - The length of the @param_values array. - - - - An array of #GValues holding the arguments - on which to invoke the callback of closure. - - - - The invocation hint given as the last argument to - g_closure_invoke(). - - - - Additional data specified when registering the - marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - - - A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue which can store the returned #gboolean - - - - 2 - - - - a #GValue array holding instance and arg1 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - a #GValue, which can store the returned string - - - - 3 - - - - a #GValue array holding instance, arg1 and arg2 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gboolean parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GBoxed* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gchar parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gdouble parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the enumeration parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the flags parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gfloat parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gint parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #glong parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GObject* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GParamSpec* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gpointer parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gchar* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #guchar parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #guint parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 3 - - - - a #GValue array holding instance, arg1 and arg2 - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #gulong parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 2 - - - - a #GValue array holding the instance and the #GVariant* parameter - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. - - - - - - - the #GClosure to which the marshaller belongs - - - - ignored - - - - 1 - - - - a #GValue array holding only the instance - - - - the invocation hint given as the last argument - to g_closure_invoke() - - - - additional data specified when registering the marshaller - - - - - - A generic marshaller function implemented via -[libffi](http://sourceware.org/libffi/). - -Normally this function is not passed explicitly to g_signal_new(), -but used automatically by GLib when specifying a %NULL marshaller. - - - - - - - A #GClosure. - - - - A #GValue to store the return value. May be %NULL - if the callback of closure doesn't return a value. - - - - The length of the @param_values array. - - - - An array of #GValues holding the arguments - on which to invoke the callback of closure. - - - - The invocation hint given as the last argument to - g_closure_invoke(). - - - - Additional data specified when registering the - marshaller, see g_closure_set_marshal() and - g_closure_set_meta_marshal() - - - - - - Creates a new closure which invokes @callback_func with @user_data as -the last parameter. - -@destroy_data will be called as a finalize notifier on the #GClosure. - - - a floating reference to a new #GCClosure - - - - - the function to invoke - - - - user data to pass to @callback_func - - - - destroy notify to be called when @user_data is no longer used - - - - - - A variant of g_cclosure_new() which uses @object as @user_data and -calls g_object_watch_closure() on @object and the created -closure. This function is useful when you have a callback closely -associated with a #GObject, and want the callback to no longer run -after the object is is freed. - - - a new #GCClosure - - - - - the function to invoke - - - - a #GObject pointer to pass to @callback_func - - - - - - A variant of g_cclosure_new_swap() which uses @object as @user_data -and calls g_object_watch_closure() on @object and the created -closure. This function is useful when you have a callback closely -associated with a #GObject, and want the callback to no longer run -after the object is is freed. - - - a new #GCClosure - - - - - the function to invoke - - - - a #GObject pointer to pass to @callback_func - - - - - - Creates a new closure which invokes @callback_func with @user_data as -the first parameter. - -@destroy_data will be called as a finalize notifier on the #GClosure. - - - a floating reference to a new #GCClosure - - - - - the function to invoke - - - - user data to pass to @callback_func - - - - destroy notify to be called when @user_data is no longer used - - - - - - Clears a reference to a #GObject. - -@object_ptr must not be %NULL. - -If the reference is %NULL then this function does nothing. -Otherwise, the reference count of the object is decreased and the -pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - a pointer to a #GObject reference - - - - - - Disconnects a handler from @instance so it will not be called during -any future or currently ongoing emissions of the signal it has been -connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()). - -If the handler ID is 0 then this function does nothing. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - A pointer to a handler ID (of type #gulong) of the handler to be disconnected. - - - - The instance to remove the signal handler from. - - - - - - Clears a weak reference to a #GObject. - -@weak_pointer_location must not be %NULL. - -If the weak reference is %NULL then this function does nothing. -Otherwise, the weak reference to the object is removed for that location -and the pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. The function itself is static inline, so its address may vary -between compilation units. - - - - The memory address of a pointer - - - - - This function is meant to be called from the `complete_type_info` -function of a #GTypePlugin implementation, as in the following -example: - -|[<!-- language="C" --> -static void -my_enum_complete_type_info (GTypePlugin *plugin, - GType g_type, - GTypeInfo *info, - GTypeValueTable *value_table) -{ - static const GEnumValue values[] = { - { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, - { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, - { 0, NULL, NULL } - }; - - g_enum_complete_type_info (type, info, values); -} -]| - - - - - - - the type identifier of the type being completed - - - - the #GTypeInfo struct to be filled in - - - - An array of #GEnumValue structs for the possible - enumeration values. The array is terminated by a struct with all - members being 0. - - - - - - Returns the #GEnumValue for a value. - - - the #GEnumValue for @value, or %NULL - if @value is not a member of the enumeration - - - - - a #GEnumClass - - - - the value to look up - - - - - - Looks up a #GEnumValue by name. - - - the #GEnumValue with name @name, - or %NULL if the enumeration doesn't have a member - with that name - - - - - a #GEnumClass - - - - the name to look up - - - - - - Looks up a #GEnumValue by nickname. - - - the #GEnumValue with nickname @nick, - or %NULL if the enumeration doesn't have a member - with that nickname - - - - - a #GEnumClass - - - - the nickname to look up - - - - - - Registers a new static enumeration type with the name @name. - -It is normally more convenient to let [glib-mkenums][glib-mkenums], -generate a my_enum_get_type() function from a usual C enumeration -definition than to write one yourself using g_enum_register_static(). - - - The new type identifier. - - - - - A nul-terminated string used as the name of the new type. - - - - An array of #GEnumValue structs for the possible - enumeration values. The array is terminated by a struct with all - members being 0. GObject keeps a reference to the data, so it cannot - be stack-allocated. - - - - - - Pretty-prints @value in the form of the enum’s name. - -This is intended to be used for debugging purposes. The format of the output -may change in the future. - - - a newly-allocated text string - - - - - the type identifier of a #GEnumClass type - - - - the value - - - - - - This function is meant to be called from the complete_type_info() -function of a #GTypePlugin implementation, see the example for -g_enum_complete_type_info() above. - - - - - - - the type identifier of the type being completed - - - - the #GTypeInfo struct to be filled in - - - - An array of #GFlagsValue structs for the possible - enumeration values. The array is terminated by a struct with all - members being 0. - - - - - - Returns the first #GFlagsValue which is set in @value. - - - the first #GFlagsValue which is set in - @value, or %NULL if none is set - - - - - a #GFlagsClass - - - - the value - - - - - - Looks up a #GFlagsValue by name. - - - the #GFlagsValue with name @name, - or %NULL if there is no flag with that name - - - - - a #GFlagsClass - - - - the name to look up - - - - - - Looks up a #GFlagsValue by nickname. - - - the #GFlagsValue with nickname @nick, - or %NULL if there is no flag with that nickname - - - - - a #GFlagsClass - - - - the nickname to look up - - - - - - Registers a new static flags type with the name @name. - -It is normally more convenient to let [glib-mkenums][glib-mkenums] -generate a my_flags_get_type() function from a usual C enumeration -definition than to write one yourself using g_flags_register_static(). - - - The new type identifier. - - - - - A nul-terminated string used as the name of the new type. - - - - An array of #GFlagsValue structs for the possible - flags values. The array is terminated by a struct with all members being 0. - GObject keeps a reference to the data, so it cannot be stack-allocated. - - - - - - Pretty-prints @value in the form of the flag names separated by ` | ` and -sorted. Any extra bits will be shown at the end as a hexadecimal number. - -This is intended to be used for debugging purposes. The format of the output -may change in the future. - - - a newly-allocated text string - - - - - the type identifier of a #GFlagsClass type - - - - the value - - - - - - - - - - - - Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN -property. In many cases, it may be more appropriate to use an enum with -g_param_spec_enum(), both to improve code clarity by using explicitly named -values, and to allow for more values to be added in future without breaking -API. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED -derived property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - %G_TYPE_BOXED derived type of this property - - - - flags for the property specified - - - - - - Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GType derived from %G_TYPE_ENUM - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GType derived from %G_TYPE_FLAGS - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecGType instance specifying a -%G_TYPE_GTYPE property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GType whose subtypes are allowed as values - of the property (use %G_TYPE_NONE for any type) - - - - flags for the property specified - - - - - - Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT -derived property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - %G_TYPE_OBJECT derived type of this property - - - - flags for the property specified - - - - - - Creates a new property of type #GParamSpecOverride. This is used -to direct operations to another paramspec, and will not be directly -useful unless you are implementing a new base type similar to GObject. - - - the newly created #GParamSpec - - - - - the name of the property. - - - - The property that is being overridden - - - - - - Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GType derived from %G_TYPE_PARAM - - - - flags for the property specified - - - - - - Creates a new #GParamSpecPointer instance specifying a pointer property. -Where possible, it is better to use g_param_spec_object() or -g_param_spec_boxed() to expose memory management information. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecPool. - -If @type_prefixing is %TRUE, lookups in the newly created pool will -allow to specify the owner as a colon-separated prefix of the -property name, like "GtkContainer:border-width". This feature is -deprecated, so you should always set @type_prefixing to %FALSE. - - - a newly allocated #GParamSpecPool. - - - - - Whether the pool will support type-prefixed property names. - - - - - - Creates a new #GParamSpecString instance. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG -property. - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value for the property specified - - - - maximum value for the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT -property. #GValue structures for this property can be accessed with -g_value_set_uint() and g_value_get_uint(). - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - default value for the property specified - - - - flags for the property specified - - - - - - Creates a new #GParamSpecValueArray instance specifying a -%G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a -%G_TYPE_BOXED type, as such, #GValue structures for this property -can be accessed with g_value_set_boxed() and g_value_get_boxed(). - -See g_param_spec_internal() for details on property names. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GParamSpec describing the elements contained in - arrays of this property, may be %NULL - - - - flags for the property specified - - - - - - Creates a new #GParamSpecVariant instance specifying a #GVariant -property. - -If @default_value is floating, it is consumed. - -See g_param_spec_internal() for details on property names. - - - the newly created #GParamSpec - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - a #GVariantType - - - - a #GVariant of type @type to - use as the default value, or %NULL - - - - flags for the property specified - - - - - - Registers @name as the name of a new static type derived from -#G_TYPE_PARAM. The type system uses the information contained in -the #GParamSpecTypeInfo structure pointed to by @info to manage the -#GParamSpec type and its instances. - - - The new type identifier. - - - - - 0-terminated string used as the name of the new #GParamSpec type. - - - - The #GParamSpecTypeInfo for this #GParamSpec type. - - - - - - Transforms @src_value into @dest_value if possible, and then -validates @dest_value, in order for it to conform to @pspec. If -@strict_validation is %TRUE this function will only succeed if the -transformed @dest_value complied to @pspec without modifications. - -See also g_value_type_transformable(), g_value_transform() and -g_param_value_validate(). - - - %TRUE if transformation and validation were successful, - %FALSE otherwise and @dest_value is left untouched. - - - - - a valid #GParamSpec - - - - souce #GValue - - - - destination #GValue of correct type for @pspec - - - - %TRUE requires @dest_value to conform to @pspec -without modifications - - - - - - Checks whether @value contains the default value as specified in @pspec. - - - whether @value contains the canonical default for this @pspec - - - - - a valid #GParamSpec - - - - a #GValue of correct type for @pspec - - - - - - Sets @value to its default value as specified in @pspec. - - - - - - - a valid #GParamSpec - - - - a #GValue of correct type for @pspec; since 2.64, you - can also pass an empty #GValue, initialized with %G_VALUE_INIT - - - - - - Ensures that the contents of @value comply with the specifications -set out by @pspec. For example, a #GParamSpecInt might require -that integers stored in @value may not be smaller than -42 and not be -greater than +42. If @value contains an integer outside of this range, -it is modified accordingly, so the resulting value will fit into the -range -42 .. +42. - - - whether modifying @value was necessary to ensure validity - - - - - a valid #GParamSpec - - - - a #GValue of correct type for @pspec - - - - - - Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, -if @value1 is found to be less than, equal to or greater than @value2, -respectively. - - - -1, 0 or +1, for a less than, equal to or greater than result - - - - - a valid #GParamSpec - - - - a #GValue of correct type for @pspec - - - - a #GValue of correct type for @pspec - - - - - - Creates a new %G_TYPE_POINTER derived type id for a new -pointer type with name @name. - - - a new %G_TYPE_POINTER derived type id for @name. - - - - - the name of the new pointer type. - - - - - - Updates a #GObject pointer to refer to @new_object. It increments the -reference count of @new_object (if non-%NULL), decrements the reference -count of the current value of @object_ptr (if non-%NULL), and assigns -@new_object to @object_ptr. The assignment is not atomic. - -@object_ptr must not be %NULL. - -A macro is also included that allows this function to be used without -pointer casts. The function itself is static inline, so its address may vary -between compilation units. - -One convenient usage of this function is in implementing property setters: -|[ - void - foo_set_bar (Foo *foo, - Bar *new_bar) - { - g_return_if_fail (IS_FOO (foo)); - g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); - - if (g_set_object (&foo->bar, new_bar)) - g_object_notify (foo, "bar"); - } -]| - - - - a pointer to a #GObject reference - - - a pointer to the new #GObject to - assign to it, or %NULL to clear the pointer - - - - - Updates a pointer to weakly refer to @new_object. It assigns @new_object -to @weak_pointer_location and ensures that @weak_pointer_location will -automaticaly be set to %NULL if @new_object gets destroyed. The assignment -is not atomic. The weak reference is not thread-safe, see -g_object_add_weak_pointer() for details. - -@weak_pointer_location must not be %NULL. - -A macro is also included that allows this function to be used without -pointer casts. The function itself is static inline, so its address may vary -between compilation units. - -One convenient usage of this function is in implementing property setters: -|[ - void - foo_set_bar (Foo *foo, - Bar *new_bar) - { - g_return_if_fail (IS_FOO (foo)); - g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); - - if (g_set_weak_pointer (&foo->bar, new_bar)) - g_object_notify (foo, "bar"); - } -]| - - - - the memory address of a pointer - - - a pointer to the new #GObject to - assign to it, or %NULL to clear the pointer - - - - - A predefined #GSignalAccumulator for signals intended to be used as a -hook for application code to provide a particular value. Usually -only one such value is desired and multiple handlers for the same -signal don't make much sense (except for the case of the default -handler defined in the class structure, in which case you will -usually want the signal connection to override the class handler). - -This accumulator will use the return value from the first signal -handler that is run as the return value for the signal and not run -any further handlers (ie: the first handler "wins"). - - - standard #GSignalAccumulator result - - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - - - A predefined #GSignalAccumulator for signals that return a -boolean values. The behavior that this accumulator gives is -that a return of %TRUE stops the signal emission: no further -callbacks will be invoked, while a return of %FALSE allows -the emission to continue. The idea here is that a %TRUE return -indicates that the callback handled the signal, and no further -handling is needed. - - - standard #GSignalAccumulator result - - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - standard #GSignalAccumulator parameter - - - - - - Adds an emission hook for a signal, which will get called for any emission -of that signal, independent of the instance. This is possible only -for signals which don't have #G_SIGNAL_NO_HOOKS flag set. - - - the hook id, for later use with g_signal_remove_emission_hook(). - - - - - the signal identifier, as returned by g_signal_lookup(). - - - - the detail on which to call the hook. - - - - a #GSignalEmissionHook function. - - - - user data for @hook_func. - - - - a #GDestroyNotify for @hook_data. - - - - - - Calls the original class closure of a signal. This function should only -be called from an overridden class closure; see -g_signal_override_class_closure() and -g_signal_override_class_handler(). - - - - - - - the argument list of the signal emission. - The first element in the array is a #GValue for the instance the signal - is being emitted on. The rest are any arguments to be passed to the signal. - - - - - - Location for the return value. - - - - - - Calls the original class closure of a signal. This function should -only be called from an overridden class closure; see -g_signal_override_class_closure() and -g_signal_override_class_handler(). - - - - - - - the instance the signal is being - emitted on. - - - - parameters to be passed to the parent class closure, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - - - - - Connects a #GCallback function to a signal for a particular object. - -The handler will be called before the default handler of the signal. - -See [memory management of signal handlers][signal-memory-management] for -details on how to handle the return value and memory management of @data. - - - - the instance to connect to. - - - a string of the form "signal-name::detail". - - - the #GCallback to connect. - - - data to pass to @c_handler calls. - - - - - Connects a #GCallback function to a signal for a particular object. - -The handler will be called after the default handler of the signal. - - - - the instance to connect to. - - - a string of the form "signal-name::detail". - - - the #GCallback to connect. - - - data to pass to @c_handler calls. - - - - - Connects a closure to a signal for a particular object. - - - the handler ID (always greater than 0 for successful connections) - - - - - the instance to connect to. - - - - a string of the form "signal-name::detail". - - - - the closure to connect. - - - - whether the handler should be called before or after the - default handler of the signal. - - - - - - Connects a closure to a signal for a particular object. - - - the handler ID (always greater than 0 for successful connections) - - - - - the instance to connect to. - - - - the id of the signal. - - - - the detail. - - - - the closure to connect. - - - - whether the handler should be called before or after the - default handler of the signal. - - - - - - Connects a #GCallback function to a signal for a particular object. Similar -to g_signal_connect(), but allows to provide a #GClosureNotify for the data -which will be called when the signal handler is disconnected and no longer -used. Specify @connect_flags if you need `..._after()` or -`..._swapped()` variants of this function. - - - the handler ID (always greater than 0 for successful connections) - - - - - the instance to connect to. - - - - a string of the form "signal-name::detail". - - - - the #GCallback to connect. - - - - data to pass to @c_handler calls. - - - - a #GClosureNotify for @data. - - - - a combination of #GConnectFlags. - - - - - - This is similar to g_signal_connect_data(), but uses a closure which -ensures that the @gobject stays alive during the call to @c_handler -by temporarily adding a reference count to @gobject. - -When the @gobject is destroyed the signal handler will be automatically -disconnected. Note that this is not currently threadsafe (ie: -emitting a signal while @gobject is being destroyed in another thread -is not safe). - - - the handler id. - - - - - the instance to connect to. - - - - a string of the form "signal-name::detail". - - - - the #GCallback to connect. - - - - the object to pass as data - to @c_handler. - - - - a combination of #GConnectFlags. - - - - - - Connects a #GCallback function to a signal for a particular object. - -The instance on which the signal is emitted and @data will be swapped when -calling the handler. This is useful when calling pre-existing functions to -operate purely on the @data, rather than the @instance: swapping the -parameters avoids the need to write a wrapper function. - -For example, this allows the shorter code: -|[<!-- language="C" --> -g_signal_connect_swapped (button, "clicked", - (GCallback) gtk_widget_hide, other_widget); -]| - -Rather than the cumbersome: -|[<!-- language="C" --> -static void -button_clicked_cb (GtkButton *button, GtkWidget *other_widget) -{ - gtk_widget_hide (other_widget); -} - -... - -g_signal_connect (button, "clicked", - (GCallback) button_clicked_cb, other_widget); -]| - - - - the instance to connect to. - - - a string of the form "signal-name::detail". - - - the #GCallback to connect. - - - data to pass to @c_handler calls. - - - - - Emits a signal. - -Note that g_signal_emit() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). - - - - - - - the instance the signal is being emitted on. - - - - the signal id - - - - the detail - - - - parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - - - - - Emits a signal. - -Note that g_signal_emit_by_name() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). - - - - - - - the instance the signal is being emitted on. - - - - a string of the form "signal-name::detail". - - - - parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - - - - - Emits a signal. - -Note that g_signal_emit_valist() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). - - - - - - - the instance the signal is being - emitted on. - - - - the signal id - - - - the detail - - - - a list of parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - - - - - Emits a signal. - -Note that g_signal_emitv() doesn't change @return_value if no handlers are -connected, in contrast to g_signal_emit() and g_signal_emit_valist(). - - - - - - - argument list for the signal emission. - The first element in the array is a #GValue for the instance the signal - is being emitted on. The rest are any arguments to be passed to the signal. - - - - - - the signal id - - - - the detail - - - - Location to -store the return value of the signal emission. This must be provided if the -specified signal returns a value, but may be ignored otherwise. - - - - - - Returns the invocation hint of the innermost signal emission of instance. - - - the invocation hint of the innermost signal emission. - - - - - the instance to query - - - - - - Blocks a handler of an instance so it will not be called during any -signal emissions unless it is unblocked again. Thus "blocking" a -signal handler means to temporarily deactive it, a signal handler -has to be unblocked exactly the same amount of times it has been -blocked before to become active again. - -The @handler_id has to be a valid signal handler id, connected to a -signal of @instance. - - - - - - - The instance to block the signal handler of. - - - - Handler id of the handler to be blocked. - - - - - - Disconnects a handler from an instance so it will not be called during -any future or currently ongoing emissions of the signal it has been -connected to. The @handler_id becomes invalid and may be reused. - -The @handler_id has to be a valid signal handler id, connected to a -signal of @instance. - - - - - - - The instance to remove the signal handler from. - - - - Handler id of the handler to be disconnected. - - - - - - Finds the first signal handler that matches certain selection criteria. -The criteria mask is passed as an OR-ed combination of #GSignalMatchType -flags, and the criteria values are passed as arguments. -The match @mask has to be non-0 for successful matches. -If no handler was found, 0 is returned. - - - A valid non-0 signal handler id for a successful match. - - - - - The instance owning the signal handler to be found. - - - - Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handler has to match. - - - - Signal the handler has to be connected to. - - - - Signal detail the handler has to be connected to. - - - - The closure the handler will invoke. - - - - The C closure callback of the handler (useless for non-C closures). - - - - The closure data of the handler's closure. - - - - - - Returns whether @handler_id is the ID of a handler connected to @instance. - - - whether @handler_id identifies a handler connected to @instance. - - - - - The instance where a signal handler is sought. - - - - the handler ID. - - - - - - Undoes the effect of a previous g_signal_handler_block() call. A -blocked handler is skipped during signal emissions and will not be -invoked, unblocking it (for exactly the amount of times it has been -blocked before) reverts its "blocked" state, so the handler will be -recognized by the signal system and is called upon future or -currently ongoing signal emissions (since the order in which -handlers are called during signal emissions is deterministic, -whether the unblocked handler in question is called as part of a -currently ongoing emission depends on how far that emission has -proceeded yet). - -The @handler_id has to be a valid id of a signal handler that is -connected to a signal of @instance and is currently blocked. - - - - - - - The instance to unblock the signal handler of. - - - - Handler id of the handler to be unblocked. - - - - - - Blocks all handlers on an instance that match @func and @data. - - - - The instance to block handlers from. - - - The C closure callback of the handlers (useless for non-C closures). - - - The closure data of the handlers' closures. - - - - - Blocks all handlers on an instance that match a certain selection criteria. -The criteria mask is passed as an OR-ed combination of #GSignalMatchType -flags, and the criteria values are passed as arguments. -Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC -or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. -If no handlers were found, 0 is returned, the number of blocked handlers -otherwise. - - - The number of handlers that matched. - - - - - The instance to block handlers from. - - - - Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. - - - - Signal the handlers have to be connected to. - - - - Signal detail the handlers have to be connected to. - - - - The closure the handlers will invoke. - - - - The C closure callback of the handlers (useless for non-C closures). - - - - The closure data of the handlers' closures. - - - - - - Destroy all signal handlers of a type instance. This function is -an implementation detail of the #GObject dispose implementation, -and should not be used outside of the type system. - - - - - - - The instance whose signal handlers are destroyed - - - - - - Disconnects all handlers on an instance that match @data. - - - - The instance to remove handlers from - - - the closure data of the handlers' closures - - - - - Disconnects all handlers on an instance that match @func and @data. - - - - The instance to remove handlers from. - - - The C closure callback of the handlers (useless for non-C closures). - - - The closure data of the handlers' closures. - - - - - Disconnects all handlers on an instance that match a certain -selection criteria. The criteria mask is passed as an OR-ed -combination of #GSignalMatchType flags, and the criteria values are -passed as arguments. Passing at least one of the -%G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or -%G_SIGNAL_MATCH_DATA match flags is required for successful -matches. If no handlers were found, 0 is returned, the number of -disconnected handlers otherwise. - - - The number of handlers that matched. - - - - - The instance to remove handlers from. - - - - Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. - - - - Signal the handlers have to be connected to. - - - - Signal detail the handlers have to be connected to. - - - - The closure the handlers will invoke. - - - - The C closure callback of the handlers (useless for non-C closures). - - - - The closure data of the handlers' closures. - - - - - - Unblocks all handlers on an instance that match @func and @data. - - - - The instance to unblock handlers from. - - - The C closure callback of the handlers (useless for non-C closures). - - - The closure data of the handlers' closures. - - - - - Unblocks all handlers on an instance that match a certain selection -criteria. The criteria mask is passed as an OR-ed combination of -#GSignalMatchType flags, and the criteria values are passed as arguments. -Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC -or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. -If no handlers were found, 0 is returned, the number of unblocked handlers -otherwise. The match criteria should not apply to any handlers that are -not currently blocked. - - - The number of handlers that matched. - - - - - The instance to unblock handlers from. - - - - Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. - - - - Signal the handlers have to be connected to. - - - - Signal detail the handlers have to be connected to. - - - - The closure the handlers will invoke. - - - - The C closure callback of the handlers (useless for non-C closures). - - - - The closure data of the handlers' closures. - - - - - - Returns whether there are any handlers connected to @instance for the -given signal id and detail. - -If @detail is 0 then it will only match handlers that were connected -without detail. If @detail is non-zero then it will match handlers -connected both without detail and with the given detail. This is -consistent with how a signal emitted with @detail would be delivered -to those handlers. - -Since 2.46 this also checks for a non-default class closure being -installed, as this is basically always what you want. - -One example of when you might use this is when the arguments to the -signal are difficult to compute. A class implementor may opt to not -emit the signal if no one is attached anyway, thus saving the cost -of building the arguments. - - - %TRUE if a handler is connected to the signal, %FALSE - otherwise. - - - - - the object whose signal handlers are sought. - - - - the signal id. - - - - the detail. - - - - whether blocked handlers should count as match. - - - - - - Lists the signals by id that a certain instance or interface type -created. Further information about the signals can be acquired through -g_signal_query(). - - - Newly allocated array of signal IDs. - - - - - - - Instance or interface type. - - - - Location to store the number of signal ids for @itype. - - - - - - Given the name of the signal and the type of object it connects to, gets -the signal's identifying integer. Emitting the signal by number is -somewhat faster than using the name each time. - -Also tries the ancestors of the given type. - -The type class passed as @itype must already have been instantiated (for -example, using g_type_class_ref()) for this function to work, as signals are -always installed during class initialization. - -See g_signal_new() for details on allowed signal names. - - - the signal's identifying number, or 0 if no signal was found. - - - - - the signal's name. - - - - the type that the signal operates on. - - - - - - Given the signal's identifier, finds its name. - -Two different signals may have the same name, if they have differing types. - - - the signal name, or %NULL if the signal number was invalid. - - - - - the signal's identifying number. - - - - - - Creates a new signal. (This is usually done in the class initializer.) - -A signal name consists of segments consisting of ASCII letters and -digits, separated by either the `-` or `_` character. The first -character of a signal name must be a letter. Names which violate these -rules lead to undefined behaviour. These are the same rules as for property -naming (see g_param_spec_internal()). - -When registering a signal and looking up a signal, either separator can -be used, but they cannot be mixed. Using `-` is considerably more efficient. -Using `_` is discouraged. - -If 0 is used for @class_offset subclasses cannot override the class handler -in their class_init method by doing super_class->signal_handler = my_signal_handler. -Instead they will have to use g_signal_override_class_handler(). - -If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as -the marshaller for this signal. In some simple cases, g_signal_new() -will use a more optimized c_marshaller and va_marshaller for the signal -instead of g_cclosure_marshal_generic(). - -If @c_marshaller is non-%NULL, you need to also specify a va_marshaller -using g_signal_set_va_marshaller() or the generic va_marshaller will -be used. - - - the signal id - - - - - the name for the signal - - - - the type this signal pertains to. It will also pertain to - types which are derived from this type. - - - - a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - - - - The offset of the function pointer in the class structure - for this type. Used to invoke a class method generically. Pass 0 to - not associate a class method slot with this signal. - - - - the accumulator for this signal; may be %NULL. - - - - user data for the @accumulator. - - - - the function to translate arrays of parameter - values to signal emissions into C language callback invocations or %NULL. - - - - the type of return value, or #G_TYPE_NONE for a signal - without a return value. - - - - the number of parameter types to follow. - - - - a list of types, one for each parameter. - - - - - - Creates a new signal. (This is usually done in the class initializer.) - -This is a variant of g_signal_new() that takes a C callback instead -of a class offset for the signal's class handler. This function -doesn't need a function pointer exposed in the class structure of -an object definition, instead the function pointer is passed -directly and can be overriden by derived classes with -g_signal_override_class_closure() or -g_signal_override_class_handler()and chained to with -g_signal_chain_from_overridden() or -g_signal_chain_from_overridden_handler(). - -See g_signal_new() for information about signal names. - -If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as -the marshaller for this signal. - - - the signal id - - - - - the name for the signal - - - - the type this signal pertains to. It will also pertain to - types which are derived from this type. - - - - a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - - - - a #GCallback which acts as class implementation of - this signal. Used to invoke a class method generically. Pass %NULL to - not associate a class method with this signal. - - - - the accumulator for this signal; may be %NULL. - - - - user data for the @accumulator. - - - - the function to translate arrays of parameter - values to signal emissions into C language callback invocations or %NULL. - - - - the type of return value, or #G_TYPE_NONE for a signal - without a return value. - - - - the number of parameter types to follow. - - - - a list of types, one for each parameter. - - - - - - Creates a new signal. (This is usually done in the class initializer.) - -See g_signal_new() for details on allowed signal names. - -If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as -the marshaller for this signal. - - - the signal id - - - - - the name for the signal - - - - the type this signal pertains to. It will also pertain to - types which are derived from this type. - - - - a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - - - - The closure to invoke on signal emission; may be %NULL. - - - - the accumulator for this signal; may be %NULL. - - - - user data for the @accumulator. - - - - the function to translate arrays of parameter - values to signal emissions into C language callback invocations or %NULL. - - - - the type of return value, or #G_TYPE_NONE for a signal - without a return value. - - - - the number of parameter types in @args. - - - - va_list of #GType, one for each parameter. - - - - - - Creates a new signal. (This is usually done in the class initializer.) - -See g_signal_new() for details on allowed signal names. - -If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as -the marshaller for this signal. - - - the signal id - - - - - the name for the signal - - - - the type this signal pertains to. It will also pertain to - types which are derived from this type - - - - a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - - - - The closure to invoke on signal emission; - may be %NULL - - - - the accumulator for this signal; may be %NULL - - - - user data for the @accumulator - - - - the function to translate arrays of - parameter values to signal emissions into C language callback - invocations or %NULL - - - - the type of return value, or #G_TYPE_NONE for a signal - without a return value - - - - the length of @param_types - - - - an array of types, one for - each parameter - - - - - - - - Overrides the class closure (i.e. the default handler) for the given signal -for emissions on instances of @instance_type. @instance_type must be derived -from the type to which the signal belongs. - -See g_signal_chain_from_overridden() and -g_signal_chain_from_overridden_handler() for how to chain up to the -parent class closure from inside the overridden one. - - - - - - - the signal id - - - - the instance type on which to override the class closure - for the signal. - - - - the closure. - - - - - - Overrides the class closure (i.e. the default handler) for the -given signal for emissions on instances of @instance_type with -callback @class_handler. @instance_type must be derived from the -type to which the signal belongs. - -See g_signal_chain_from_overridden() and -g_signal_chain_from_overridden_handler() for how to chain up to the -parent class closure from inside the overridden one. - - - - - - - the name for the signal - - - - the instance type on which to override the class handler - for the signal. - - - - the handler. - - - - - - Internal function to parse a signal name into its @signal_id -and @detail quark. - - - Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. - - - - - a string of the form "signal-name::detail". - - - - The interface/instance type that introduced "signal-name". - - - - Location to store the signal id. - - - - Location to store the detail quark. - - - - %TRUE forces creation of a #GQuark for the detail. - - - - - - Queries the signal system for in-depth information about a -specific signal. This function will fill in a user-provided -structure to hold signal-specific information. If an invalid -signal id is passed in, the @signal_id member of the #GSignalQuery -is 0. All members filled into the #GSignalQuery structure should -be considered constant and have to be left untouched. - - - - - - - The signal id of the signal to query information for. - - - - A user provided structure that is - filled in with constant values upon success. - - - - - - Deletes an emission hook. - - - - - - - the id of the signal - - - - the id of the emission hook, as returned by - g_signal_add_emission_hook() - - - - - - Change the #GSignalCVaMarshaller used for a given signal. This is a -specialised form of the marshaller that can often be used for the -common case of a single connected signal handler and avoids the -overhead of #GValue. Its use is optional. - - - - - - - the signal id - - - - the instance type on which to set the marshaller. - - - - the marshaller to set. - - - - - - Stops a signal's current emission. - -This will prevent the default method from running, if the signal was -%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" -flag). - -Prints a warning if used on a signal which isn't being emitted. - - - - - - - the object whose signal handlers you wish to stop. - - - - the signal identifier, as returned by g_signal_lookup(). - - - - the detail which the signal was emitted with. - - - - - - Stops a signal's current emission. - -This is just like g_signal_stop_emission() except it will look up the -signal id for you. - - - - - - - the object whose signal handlers you wish to stop. - - - - a string of the form "signal-name::detail". - - - - - - Creates a new closure which invokes the function found at the offset -@struct_offset in the class structure of the interface or classed type -identified by @itype. - - - a floating reference to a new #GCClosure - - - - - the #GType identifier of an interface or classed type - - - - the offset of the member function of @itype's class - structure which is to be invoked by the new closure - - - - - - Set the callback for a source as a #GClosure. - -If the source is not one of the standard GLib types, the @closure_callback -and @closure_marshal fields of the #GSourceFuncs structure must have been -filled in with pointers to appropriate functions. - - - - - - - the source - - - - a #GClosure - - - - - - Sets a dummy callback for @source. The callback will do nothing, and -if the source expects a #gboolean return value, it will return %TRUE. -(If the source expects any other type of return value, it will return -a 0/%NULL value; whatever g_value_init() initializes a #GValue to for -that type.) - -If the source is not one of the standard GLib types, the -@closure_callback and @closure_marshal fields of the #GSourceFuncs -structure must have been filled in with pointers to appropriate -functions. - - - - - - - the source - - - - - - Return a newly allocated string, which describes the contents of a -#GValue. The main purpose of this function is to describe #GValue -contents for debugging output, the way in which the contents are -described may change between different GLib versions. - - - Newly allocated string. - - - - - #GValue which contents are to be described. - - - - - - Adds a #GTypeClassCacheFunc to be called before the reference count of a -class goes from one to zero. This can be used to prevent premature class -destruction. All installed #GTypeClassCacheFunc functions will be chained -until one of them returns %TRUE. The functions have to check the class id -passed in to figure whether they actually want to cache the class of this -type, since all classes are routed through the same #GTypeClassCacheFunc -chain. - - - - - - - data to be passed to @cache_func - - - - a #GTypeClassCacheFunc - - - - - - Registers a private class structure for a classed type; -when the class is allocated, the private structures for -the class and all of its parent types are allocated -sequentially in the same memory block as the public -structures, and are zero-filled. - -This function should be called in the -type's get_type() function after the type is registered. -The private structure can be retrieved using the -G_TYPE_CLASS_GET_PRIVATE() macro. - - - - - - - GType of a classed type - - - - size of private structure - - - - - - - - - - - - - - - - - - - - Adds a function to be called after an interface vtable is -initialized for any class (i.e. after the @interface_init -member of #GInterfaceInfo has been called). - -This function is useful when you want to check an invariant -that depends on the interfaces of a class. For instance, the -implementation of #GObject uses this facility to check that an -object implements all of the properties that are defined on its -interfaces. - - - - - - - data to pass to @check_func - - - - function to be called after each interface - is initialized - - - - - - Adds @interface_type to the dynamic @instantiable_type. The information -contained in the #GTypePlugin structure pointed to by @plugin -is used to manage the relationship. - - - - - - - #GType value of an instantiable type - - - - #GType value of an interface type - - - - #GTypePlugin structure to retrieve the #GInterfaceInfo from - - - - - - Adds @interface_type to the static @instantiable_type. -The information contained in the #GInterfaceInfo structure -pointed to by @info is used to manage the relationship. - - - - - - - #GType value of an instantiable type - - - - #GType value of an interface type - - - - #GInterfaceInfo structure for this - (@instance_type, @interface_type) combination - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Private helper function to aid implementation of the -G_TYPE_CHECK_INSTANCE() macro. - - - %TRUE if @instance is valid, %FALSE otherwise - - - - - a valid #GTypeInstance structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Return a newly allocated and 0-terminated array of type IDs, listing -the child types of @type. - - - Newly allocated - and 0-terminated array of child types, free with g_free() - - - - - - - the parent type - - - - location to store the length of - the returned array, or %NULL - - - - - - - - - - - - - - - - - - - - This function is essentially the same as g_type_class_ref(), -except that the classes reference count isn't incremented. -As a consequence, this function may return %NULL if the class -of the type passed in does not currently exist (hasn't been -referenced before). - - - the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist - - - - - type ID of a classed type - - - - - - A more efficient version of g_type_class_peek() which works only for -static types. - - - the #GTypeClass - structure for the given type ID or %NULL if the class does not - currently exist or is dynamically loaded - - - - - type ID of a classed type - - - - - - Increments the reference count of the class structure belonging to -@type. This function will demand-create the class if it doesn't -exist already. - - - the #GTypeClass - structure for the given type ID - - - - - type ID of a classed type - - - - - - Creates and initializes an instance of @type if @type is valid and -can be instantiated. The type system only performs basic allocation -and structure setups for instances: actual instance creation should -happen through functions supplied by the type's fundamental type -implementation. So use of g_type_create_instance() is reserved for -implementators of fundamental types only. E.g. instances of the -#GObject hierarchy should be created via g_object_new() and never -directly through g_type_create_instance() which doesn't handle things -like singleton objects or object construction. - -The extended members of the returned instance are guaranteed to be filled -with zeros. - -Note: Do not use this function, unless you're implementing a -fundamental type. Also language bindings should not use this -function, but g_object_new() instead. - - - an allocated and initialized instance, subject to further - treatment by the fundamental type implementation - - - - - an instantiatable type to create an instance for - - - - - - If the interface type @g_type is currently in use, returns its -default interface vtable. - - - the default - vtable for the interface, or %NULL if the type is not currently - in use - - - - - an interface type - - - - - - Increments the reference count for the interface type @g_type, -and returns the default interface vtable for the type. - -If the type is not currently in use, then the default vtable -for the type will be created and initalized by calling -the base interface init and default vtable init functions for -the type (the @base_init and @class_init members of #GTypeInfo). -Calling g_type_default_interface_ref() is useful when you -want to make sure that signals and properties for an interface -have been installed. - - - the default - vtable for the interface; call g_type_default_interface_unref() - when you are done using the interface. - - - - - an interface type - - - - - - Decrements the reference count for the type corresponding to the -interface default vtable @g_iface. If the type is dynamic, then -when no one is using the interface and all references have -been released, the finalize function for the interface's default -vtable (the @class_finalize member of #GTypeInfo) will be called. - - - - - - - the default vtable - structure for an interface, as returned by g_type_default_interface_ref() - - - - - - Returns the length of the ancestry of the passed in type. This -includes the type itself, so that e.g. a fundamental type has depth 1. - - - the depth of @type - - - - - a #GType - - - - - - Ensures that the indicated @type has been registered with the -type system, and its _class_init() method has been run. - -In theory, simply calling the type's _get_type() method (or using -the corresponding macro) is supposed take care of this. However, -_get_type() methods are often marked %G_GNUC_CONST for performance -reasons, even though this is technically incorrect (since -%G_GNUC_CONST requires that the function not have side effects, -which _get_type() methods do on the first call). As a result, if -you write a bare call to a _get_type() macro, it may get optimized -out by the compiler. Using g_type_ensure() guarantees that the -type's _get_type() method is called. - - - - - - - a #GType - - - - - - Frees an instance of a type, returning it to the instance pool for -the type, if there is one. - -Like g_type_create_instance(), this function is reserved for -implementors of fundamental types. - - - - - - - an instance of a type - - - - - - Look up the type ID from a given type name, returning 0 if no type -has been registered under this name (this is the preferred method -to find out by name whether a specific type has been registered -yet). - - - corresponding type ID or 0 - - - - - type name to look up - - - - - - Internal function, used to extract the fundamental type ID portion. -Use G_TYPE_FUNDAMENTAL() instead. - - - fundamental type ID - - - - - valid type ID - - - - - - Returns the next free fundamental type id which can be used to -register a new fundamental type with g_type_register_fundamental(). -The returned type ID represents the highest currently registered -fundamental type identifier. - - - the next available fundamental type ID to be registered, - or 0 if the type system ran out of fundamental type IDs - - - - - Returns the number of instances allocated of the particular type; -this is only available if GLib is built with debugging support and -the instance_count debug flag is set (by setting the GOBJECT_DEBUG -variable to include instance-count). - - - the number of instances allocated of the given type; - if instance counts are not available, returns 0. - - - - - a #GType - - - - - - Returns the #GTypePlugin structure for @type. - - - the corresponding plugin - if @type is a dynamic type, %NULL otherwise - - - - - #GType to retrieve the plugin for - - - - - - Obtains data which has previously been attached to @type -with g_type_set_qdata(). - -Note that this does not take subtyping into account; data -attached to one type with g_type_set_qdata() cannot -be retrieved from a subtype using g_type_get_qdata(). - - - the data, or %NULL if no data was found - - - - - a #GType - - - - a #GQuark id to identify the data - - - - - - Returns an opaque serial number that represents the state of the set -of registered types. Any time a type is registered this serial changes, -which means you can cache information based on type lookups (such as -g_type_from_name()) and know if the cache is still valid at a later -time by comparing the current serial with the one at the type lookup. - - - An unsigned int, representing the state of type registrations - - - - - This function used to initialise the type system. Since GLib 2.36, -the type system is initialised automatically and this function does -nothing. - the type system is now initialised automatically - - - - - - - This function used to initialise the type system with debugging -flags. Since GLib 2.36, the type system is initialised automatically -and this function does nothing. - -If you need to enable debugging features, use the GOBJECT_DEBUG -environment variable. - the type system is now initialised automatically - - - - - - - bitwise combination of #GTypeDebugFlags values for - debugging purposes - - - - - - Adds @prerequisite_type to the list of prerequisites of @interface_type. -This means that any type implementing @interface_type must also implement -@prerequisite_type. Prerequisites can be thought of as an alternative to -interface derivation (which GType doesn't support). An interface can have -at most one instantiatable prerequisite type. - - - - - - - #GType value of an interface type - - - - #GType value of an interface or instantiatable type - - - - - - Returns the #GTypePlugin structure for the dynamic interface -@interface_type which has been added to @instance_type, or %NULL -if @interface_type has not been added to @instance_type or does -not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - - - the #GTypePlugin for the dynamic - interface @interface_type of @instance_type - - - - - #GType of an instantiatable type - - - - #GType of an interface type - - - - - - Returns the #GTypeInterface structure of an interface to which the -passed in class conforms. - - - the #GTypeInterface - structure of @iface_type if implemented by @instance_class, %NULL - otherwise - - - - - a #GTypeClass structure - - - - an interface ID which this class conforms to - - - - - - Returns the prerequisites of an interfaces type. - - - a - newly-allocated zero-terminated array of #GType containing - the prerequisites of @interface_type - - - - - - - an interface type - - - - location to return the number - of prerequisites, or %NULL - - - - - - Return a newly allocated and 0-terminated array of type IDs, listing -the interface types that @type conforms to. - - - Newly allocated - and 0-terminated array of interface types, free with g_free() - - - - - - - the type to list interface types for - - - - location to store the length of - the returned array, or %NULL - - - - - - If @is_a_type is a derivable type, check whether @type is a -descendant of @is_a_type. If @is_a_type is an interface, check -whether @type conforms to it. - - - %TRUE if @type is a @is_a_type - - - - - type to check anchestry for - - - - possible anchestor of @type or interface that @type - could conform to - - - - - - Get the unique name that is assigned to a type ID. Note that this -function (like all other GType API) cannot cope with invalid type -IDs. %G_TYPE_INVALID may be passed to this function, as may be any -other validly registered type ID, but randomized type IDs should -not be passed in and will most likely lead to a crash. - - - static type name or %NULL - - - - - type to return name for - - - - - - - - - - - - - - - - - - - - - - - - - - - - Given a @leaf_type and a @root_type which is contained in its -anchestry, return the type that @root_type is the immediate parent -of. In other words, this function determines the type that is -derived directly from @root_type which is also a base class of -@leaf_type. Given a root type and a leaf type, this function can -be used to determine the types and order in which the leaf type is -descended from the root type. - - - immediate child of @root_type and anchestor of @leaf_type - - - - - descendant of @root_type and the type to be returned - - - - immediate parent of the returned type - - - - - - Return the direct parent type of the passed in type. If the passed -in type has no parent, i.e. is a fundamental type, 0 is returned. - - - the parent type - - - - - the derived type - - - - - - Get the corresponding quark of the type IDs name. - - - the type names quark or 0 - - - - - type to return quark of type name for - - - - - - Queries the type system for information about a specific type. -This function will fill in a user-provided structure to hold -type-specific information. If an invalid #GType is passed in, the -@type member of the #GTypeQuery is 0. All members filled into the -#GTypeQuery structure should be considered constant and have to be -left untouched. - - - - - - - #GType of a static, classed type - - - - a user provided structure that is - filled in with constant values upon success - - - - - - Registers @type_name as the name of a new dynamic type derived from -@parent_type. The type system uses the information contained in the -#GTypePlugin structure pointed to by @plugin to manage the type and its -instances (if not abstract). The value of @flags determines the nature -(e.g. abstract or not) of the type. - - - the new type identifier or #G_TYPE_INVALID if registration failed - - - - - type from which this type will be derived - - - - 0-terminated string used as the name of the new type - - - - #GTypePlugin structure to retrieve the #GTypeInfo from - - - - bitwise combination of #GTypeFlags values - - - - - - Registers @type_id as the predefined identifier and @type_name as the -name of a fundamental type. If @type_id is already registered, or a -type named @type_name is already registered, the behaviour is undefined. -The type system uses the information contained in the #GTypeInfo structure -pointed to by @info and the #GTypeFundamentalInfo structure pointed to by -@finfo to manage the type and its instances. The value of @flags determines -additional characteristics of the fundamental type. - - - the predefined type identifier - - - - - a predefined type identifier - - - - 0-terminated string used as the name of the new type - - - - #GTypeInfo structure for this type - - - - #GTypeFundamentalInfo structure for this type - - - - bitwise combination of #GTypeFlags values - - - - - - Registers @type_name as the name of a new static type derived from -@parent_type. The type system uses the information contained in the -#GTypeInfo structure pointed to by @info to manage the type and its -instances (if not abstract). The value of @flags determines the nature -(e.g. abstract or not) of the type. - - - the new type identifier - - - - - type from which this type will be derived - - - - 0-terminated string used as the name of the new type - - - - #GTypeInfo structure for this type - - - - bitwise combination of #GTypeFlags values - - - - - - Registers @type_name as the name of a new static type derived from -@parent_type. The value of @flags determines the nature (e.g. -abstract or not) of the type. It works by filling a #GTypeInfo -struct and calling g_type_register_static(). - - - the new type identifier - - - - - type from which this type will be derived - - - - 0-terminated string used as the name of the new type - - - - size of the class structure (see #GTypeInfo) - - - - location of the class initialization function (see #GTypeInfo) - - - - size of the instance structure (see #GTypeInfo) - - - - location of the instance initialization function (see #GTypeInfo) - - - - bitwise combination of #GTypeFlags values - - - - - - Removes a previously installed #GTypeClassCacheFunc. The cache -maintained by @cache_func has to be empty when calling -g_type_remove_class_cache_func() to avoid leaks. - - - - - - - data that was given when adding @cache_func - - - - a #GTypeClassCacheFunc - - - - - - Removes an interface check function added with -g_type_add_interface_check(). - - - - - - - callback data passed to g_type_add_interface_check() - - - - callback function passed to g_type_add_interface_check() - - - - - - Attaches arbitrary data to a type. - - - - - - - a #GType - - - - a #GQuark id to identify the data - - - - the data - - - - - - - - - - - - - - - - - - - - Returns the location of the #GTypeValueTable associated with @type. - -Note that this function should only be used from source code -that implements or has internal knowledge of the implementation of -@type. - - - location of the #GTypeValueTable associated with @type or - %NULL if there is no #GTypeValueTable associated with @type - - - - - a #GType - - - - - - Registers a value transformation function for use in g_value_transform(). -A previously registered transformation function for @src_type and @dest_type -will be replaced. - - - - - - - Source type. - - - - Target type. - - - - a function which transforms values of type @src_type - into value of type @dest_type - - - - - - Returns whether a #GValue of type @src_type can be copied into -a #GValue of type @dest_type. - - - %TRUE if g_value_copy() is possible with @src_type and @dest_type. - - - - - source type to be copied. - - - - destination type for copying. - - - - - - Check whether g_value_transform() is able to transform values -of type @src_type into values of type @dest_type. Note that for -the types to be transformable, they must be compatible or a -transformation function must be registered. - - - %TRUE if the transformation is possible, %FALSE otherwise. - - - - - Source type. - - - - Target type. - - - - - - diff --git a/gir-files/Gio-2.0.gir b/gir-files/Gio-2.0.gir deleted file mode 100644 index 81002126f..000000000 --- a/gir-files/Gio-2.0.gir +++ /dev/null @@ -1,89324 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GAction represents a single named action. - -The main interface to an action is that it can be activated with -g_action_activate(). This results in the 'activate' signal being -emitted. An activation has a #GVariant parameter (which may be -%NULL). The correct type for the parameter is determined by a static -parameter type (which is given at construction time). - -An action may optionally have a state, in which case the state may be -set with g_action_change_state(). This call takes a #GVariant. The -correct type for the state is determined by a static state type -(which is given at construction time). - -The state may have a hint associated with it, specifying its valid -range. - -#GAction is merely the interface to the concept of an action, as -described above. Various implementations of actions exist, including -#GSimpleAction. - -In all cases, the implementing class is responsible for storing the -name of the action, the parameter type, the enabled state, the -optional state type and the state and emitting the appropriate -signals when these change. The implementor is responsible for filtering -calls to g_action_activate() and g_action_change_state() for type -safety and for the state being enabled. - -Probably the only useful thing to do with a #GAction is to put it -inside of a #GSimpleActionGroup. - - - Checks if @action_name is valid. - -@action_name is valid if it consists only of alphanumeric characters, -plus '-' and '.'. The empty string is not a valid action name. - -It is an error to call this function with a non-utf8 @action_name. -@action_name must not be %NULL. - - - %TRUE if @action_name is valid - - - - - a potential action name - - - - - - Parses a detailed action name into its separate name and target -components. - -Detailed action names can have three formats. - -The first format is used to represent an action name with no target -value and consists of just an action name containing no whitespace -nor the characters ':', '(' or ')'. For example: "app.action". - -The second format is used to represent an action with a target value -that is a non-empty string consisting only of alphanumerics, plus '-' -and '.'. In that case, the action name and target value are -separated by a double colon ("::"). For example: -"app.action::target". - -The third format is used to represent an action with any type of -target value, including strings. The target value follows the action -name, surrounded in parens. For example: "app.action(42)". The -target value is parsed using g_variant_parse(). If a tuple-typed -value is desired, it must be specified in the same way, resulting in -two sets of parens, for example: "app.action((1,2,3))". A string -target can be specified this way as well: "app.action('target')". -For strings, this third format must be used if * target value is -empty or contains characters other than alphanumerics, '-' and '.'. - - - %TRUE if successful, else %FALSE with @error set - - - - - a detailed action name - - - - the action name - - - - the target value, or %NULL for no target - - - - - - Formats a detailed action name from @action_name and @target_value. - -It is an error to call this function with an invalid action name. - -This function is the opposite of g_action_parse_detailed_name(). -It will produce a string that can be parsed back to the @action_name -and @target_value by that function. - -See that function for the types of strings that will be printed by -this function. - - - a detailed format string - - - - - a valid action name - - - - a #GVariant target value, or %NULL - - - - - - Activates the action. - -@parameter must be the correct type of parameter for the action (ie: -the parameter type given at construction time). If the parameter -type was %NULL then @parameter must also be %NULL. - -If the @parameter GVariant is floating, it is consumed. - - - - - - - a #GAction - - - - the parameter to the activation - - - - - - Request for the state of @action to be changed to @value. - -The action must be stateful and @value must be of the correct type. -See g_action_get_state_type(). - -This call merely requests a change. The action may refuse to change -its state or may change its state to something other than @value. -See g_action_get_state_hint(). - -If the @value GVariant is floating, it is consumed. - - - - - - - a #GAction - - - - the new state - - - - - - Checks if @action is currently enabled. - -An action must be enabled in order to be activated or in order to -have its state changed from outside callers. - - - whether the action is enabled - - - - - a #GAction - - - - - - Queries the name of @action. - - - the name of the action - - - - - a #GAction - - - - - - Queries the type of the parameter that must be given when activating -@action. - -When activating the action using g_action_activate(), the #GVariant -given to that function must be of the type returned by this function. - -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - - - the parameter type - - - - - a #GAction - - - - - - Queries the current state of @action. - -If the action is not stateful then %NULL will be returned. If the -action is stateful then the type of the return value is the type -given by g_action_get_state_type(). - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the current state of the action - - - - - a #GAction - - - - - - Requests a hint about the valid range of values for the state of -@action. - -If %NULL is returned it either means that the action is not stateful -or that there is no hint about the valid range of values for the -state of the action. - -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is -returned then the tuple specifies the inclusive lower and upper bound -of valid values for the state. - -In any case, the information is merely a hint. It may be possible to -have a state value outside of the hinted range and setting a value -within the range may fail. - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the state range hint - - - - - a #GAction - - - - - - Queries the type of the state of @action. - -If the action is stateful (e.g. created with -g_simple_action_new_stateful()) then this function returns the -#GVariantType of the state. This is the type of the initial value -given as the state. All calls to g_action_change_state() must give a -#GVariant of this type and g_action_get_state() will return a -#GVariant of the same type. - -If the action is not stateful (e.g. created with g_simple_action_new()) -then this function will return %NULL. In that case, g_action_get_state() -will return %NULL and you must not call g_action_change_state(). - - - the state type, if the action is stateful - - - - - a #GAction - - - - - - Activates the action. - -@parameter must be the correct type of parameter for the action (ie: -the parameter type given at construction time). If the parameter -type was %NULL then @parameter must also be %NULL. - -If the @parameter GVariant is floating, it is consumed. - - - - - - - a #GAction - - - - the parameter to the activation - - - - - - Request for the state of @action to be changed to @value. - -The action must be stateful and @value must be of the correct type. -See g_action_get_state_type(). - -This call merely requests a change. The action may refuse to change -its state or may change its state to something other than @value. -See g_action_get_state_hint(). - -If the @value GVariant is floating, it is consumed. - - - - - - - a #GAction - - - - the new state - - - - - - Checks if @action is currently enabled. - -An action must be enabled in order to be activated or in order to -have its state changed from outside callers. - - - whether the action is enabled - - - - - a #GAction - - - - - - Queries the name of @action. - - - the name of the action - - - - - a #GAction - - - - - - Queries the type of the parameter that must be given when activating -@action. - -When activating the action using g_action_activate(), the #GVariant -given to that function must be of the type returned by this function. - -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - - - the parameter type - - - - - a #GAction - - - - - - Queries the current state of @action. - -If the action is not stateful then %NULL will be returned. If the -action is stateful then the type of the return value is the type -given by g_action_get_state_type(). - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the current state of the action - - - - - a #GAction - - - - - - Requests a hint about the valid range of values for the state of -@action. - -If %NULL is returned it either means that the action is not stateful -or that there is no hint about the valid range of values for the -state of the action. - -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is -returned then the tuple specifies the inclusive lower and upper bound -of valid values for the state. - -In any case, the information is merely a hint. It may be possible to -have a state value outside of the hinted range and setting a value -within the range may fail. - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the state range hint - - - - - a #GAction - - - - - - Queries the type of the state of @action. - -If the action is stateful (e.g. created with -g_simple_action_new_stateful()) then this function returns the -#GVariantType of the state. This is the type of the initial value -given as the state. All calls to g_action_change_state() must give a -#GVariant of this type and g_action_get_state() will return a -#GVariant of the same type. - -If the action is not stateful (e.g. created with g_simple_action_new()) -then this function will return %NULL. In that case, g_action_get_state() -will return %NULL and you must not call g_action_change_state(). - - - the state type, if the action is stateful - - - - - a #GAction - - - - - - If @action is currently enabled. - -If the action is disabled then calls to g_action_activate() and -g_action_change_state() have no effect. - - - - The name of the action. This is mostly meaningful for identifying -the action once it has been added to a #GActionGroup. It is immutable. - - - - The type of the parameter that must be given when activating the -action. This is immutable, and may be %NULL if no parameter is needed when -activating the action. - - - - The state of the action, or %NULL if the action is stateless. - - - - The #GVariantType of the state that the action has, or %NULL if the -action is stateless. This is immutable. - - - - - This struct defines a single action. It is for use with -g_action_map_add_action_entries(). - -The order of the items in the structure are intended to reflect -frequency of use. It is permissible to use an incomplete initialiser -in order to leave some of the later values as %NULL. All values -after @name are optional. Additional optional fields may be added in -the future. - -See g_action_map_add_action_entries() for an example. - - - the name of the action - - - - - - - - - - - - - - - - - - - - - - - the type of the parameter that must be passed to the - activate function for this action, given as a single - GVariant type string (or %NULL for no parameter) - - - - the initial state for this action, given in - [GVariant text format][gvariant-text]. The state is parsed - with no extra type information, so type tags must be added to - the string if they are necessary. Stateless actions should - give %NULL here. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GActionGroup represents a group of actions. Actions can be used to -expose functionality in a structured way, either from one part of a -program to another, or to the outside world. Action groups are often -used together with a #GMenuModel that provides additional -representation data for displaying the actions to the user, e.g. in -a menu. - -The main way to interact with the actions in a GActionGroup is to -activate them with g_action_group_activate_action(). Activating an -action may require a #GVariant parameter. The required type of the -parameter can be inquired with g_action_group_get_action_parameter_type(). -Actions may be disabled, see g_action_group_get_action_enabled(). -Activating a disabled action has no effect. - -Actions may optionally have a state in the form of a #GVariant. The -current state of an action can be inquired with -g_action_group_get_action_state(). Activating a stateful action may -change its state, but it is also possible to set the state by calling -g_action_group_change_action_state(). - -As typical example, consider a text editing application which has an -option to change the current font to 'bold'. A good way to represent -this would be a stateful action, with a boolean state. Activating the -action would toggle the state. - -Each action in the group has a unique name (which is a string). All -method calls, except g_action_group_list_actions() take the name of -an action as an argument. - -The #GActionGroup API is meant to be the 'public' API to the action -group. The calls here are exactly the interaction that 'external -forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have -with actions. 'Internal' APIs (ie: ones meant only to be accessed by -the action group implementation) are found on subclasses. This is -why you will find - for example - g_action_group_get_action_enabled() -but not an equivalent set() call. - -Signals are emitted on the action group in response to state changes -on individual actions. - -Implementations of #GActionGroup should provide implementations for -the virtual functions g_action_group_list_actions() and -g_action_group_query_action(). The other virtual functions should -not be implemented - their "wrappers" are actually implemented with -calls to g_action_group_query_action(). - - - Emits the #GActionGroup::action-added signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - Emits the #GActionGroup::action-enabled-changed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - whether or not the action is now enabled - - - - - - Emits the #GActionGroup::action-removed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - Emits the #GActionGroup::action-state-changed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - the new state of the named action - - - - - - Activate the named action within @action_group. - -If the action is expecting a parameter, then the correct type of -parameter must be given as @parameter. If the action is expecting no -parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). - - - - - - - a #GActionGroup - - - - the name of the action to activate - - - - parameters to the activation - - - - - - Request for the state of the named action within @action_group to be -changed to @value. - -The action must be stateful and @value must be of the correct type. -See g_action_group_get_action_state_type(). - -This call merely requests a change. The action may refuse to change -its state or may change its state to something other than @value. -See g_action_group_get_action_state_hint(). - -If the @value GVariant is floating, it is consumed. - - - - - - - a #GActionGroup - - - - the name of the action to request the change on - - - - the new state - - - - - - Checks if the named action within @action_group is currently enabled. - -An action must be enabled in order to be activated or in order to -have its state changed from outside callers. - - - whether or not the action is currently enabled - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the type of the parameter that must be given when activating -the named action within @action_group. - -When activating the action using g_action_group_activate_action(), -the #GVariant given to that function must be of the type returned -by this function. - -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - -The parameter type of a particular action will never change but it is -possible for an action to be removed and for a new action to be added -with the same name but a different parameter type. - - - the parameter type - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the current state of the named action within @action_group. - -If the action is not stateful then %NULL will be returned. If the -action is stateful then the type of the return value is the type -given by g_action_group_get_action_state_type(). - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the current state of the action - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Requests a hint about the valid range of values for the state of the -named action within @action_group. - -If %NULL is returned it either means that the action is not stateful -or that there is no hint about the valid range of values for the -state of the action. - -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is -returned then the tuple specifies the inclusive lower and upper bound -of valid values for the state. - -In any case, the information is merely a hint. It may be possible to -have a state value outside of the hinted range and setting a value -within the range may fail. - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the state range hint - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the type of the state of the named action within -@action_group. - -If the action is stateful then this function returns the -#GVariantType of the state. All calls to -g_action_group_change_action_state() must give a #GVariant of this -type and g_action_group_get_action_state() will return a #GVariant -of the same type. - -If the action is not stateful then this function will return %NULL. -In that case, g_action_group_get_action_state() will return %NULL -and you must not call g_action_group_change_action_state(). - -The state type of a particular action will never change but it is -possible for an action to be removed and for a new action to be added -with the same name but a different state type. - - - the state type, if the action is stateful - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Checks if the named action exists within @action_group. - - - whether the named action exists - - - - - a #GActionGroup - - - - the name of the action to check for - - - - - - Lists the actions contained within @action_group. - -The caller is responsible for freeing the list with g_strfreev() when -it is no longer required. - - - a %NULL-terminated array of the names of the -actions in the group - - - - - - - a #GActionGroup - - - - - - Queries all aspects of the named action within an @action_group. - -This function acquires the information available from -g_action_group_has_action(), g_action_group_get_action_enabled(), -g_action_group_get_action_parameter_type(), -g_action_group_get_action_state_type(), -g_action_group_get_action_state_hint() and -g_action_group_get_action_state() with a single function call. - -This provides two main benefits. - -The first is the improvement in efficiency that comes with not having -to perform repeated lookups of the action in order to discover -different things about it. The second is that implementing -#GActionGroup can now be done by only overriding this one virtual -function. - -The interface provides a default implementation of this function that -calls the individual functions, as required, to fetch the -information. The interface also provides default implementations of -those functions that call this function. All implementations, -therefore, must override either this function or all of the others. - -If the action exists, %TRUE is returned and any of the requested -fields (as indicated by having a non-%NULL reference passed in) are -filled. If the action doesn't exist, %FALSE is returned and the -fields may or may not have been modified. - - - %TRUE if the action exists, else %FALSE - - - - - a #GActionGroup - - - - the name of an action in the group - - - - if the action is presently enabled - - - - the parameter type, or %NULL if none needed - - - - the state type, or %NULL if stateless - - - - the state hint, or %NULL if none - - - - the current state, or %NULL if stateless - - - - - - Emits the #GActionGroup::action-added signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - Emits the #GActionGroup::action-enabled-changed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - whether or not the action is now enabled - - - - - - Emits the #GActionGroup::action-removed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - Emits the #GActionGroup::action-state-changed signal on @action_group. - -This function should only be called by #GActionGroup implementations. - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - the new state of the named action - - - - - - Activate the named action within @action_group. - -If the action is expecting a parameter, then the correct type of -parameter must be given as @parameter. If the action is expecting no -parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). - - - - - - - a #GActionGroup - - - - the name of the action to activate - - - - parameters to the activation - - - - - - Request for the state of the named action within @action_group to be -changed to @value. - -The action must be stateful and @value must be of the correct type. -See g_action_group_get_action_state_type(). - -This call merely requests a change. The action may refuse to change -its state or may change its state to something other than @value. -See g_action_group_get_action_state_hint(). - -If the @value GVariant is floating, it is consumed. - - - - - - - a #GActionGroup - - - - the name of the action to request the change on - - - - the new state - - - - - - Checks if the named action within @action_group is currently enabled. - -An action must be enabled in order to be activated or in order to -have its state changed from outside callers. - - - whether or not the action is currently enabled - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the type of the parameter that must be given when activating -the named action within @action_group. - -When activating the action using g_action_group_activate_action(), -the #GVariant given to that function must be of the type returned -by this function. - -In the case that this function returns %NULL, you must not give any -#GVariant, but %NULL instead. - -The parameter type of a particular action will never change but it is -possible for an action to be removed and for a new action to be added -with the same name but a different parameter type. - - - the parameter type - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the current state of the named action within @action_group. - -If the action is not stateful then %NULL will be returned. If the -action is stateful then the type of the return value is the type -given by g_action_group_get_action_state_type(). - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the current state of the action - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Requests a hint about the valid range of values for the state of the -named action within @action_group. - -If %NULL is returned it either means that the action is not stateful -or that there is no hint about the valid range of values for the -state of the action. - -If a #GVariant array is returned then each item in the array is a -possible value for the state. If a #GVariant pair (ie: two-tuple) is -returned then the tuple specifies the inclusive lower and upper bound -of valid values for the state. - -In any case, the information is merely a hint. It may be possible to -have a state value outside of the hinted range and setting a value -within the range may fail. - -The return value (if non-%NULL) should be freed with -g_variant_unref() when it is no longer required. - - - the state range hint - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Queries the type of the state of the named action within -@action_group. - -If the action is stateful then this function returns the -#GVariantType of the state. All calls to -g_action_group_change_action_state() must give a #GVariant of this -type and g_action_group_get_action_state() will return a #GVariant -of the same type. - -If the action is not stateful then this function will return %NULL. -In that case, g_action_group_get_action_state() will return %NULL -and you must not call g_action_group_change_action_state(). - -The state type of a particular action will never change but it is -possible for an action to be removed and for a new action to be added -with the same name but a different state type. - - - the state type, if the action is stateful - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - Checks if the named action exists within @action_group. - - - whether the named action exists - - - - - a #GActionGroup - - - - the name of the action to check for - - - - - - Lists the actions contained within @action_group. - -The caller is responsible for freeing the list with g_strfreev() when -it is no longer required. - - - a %NULL-terminated array of the names of the -actions in the group - - - - - - - a #GActionGroup - - - - - - Queries all aspects of the named action within an @action_group. - -This function acquires the information available from -g_action_group_has_action(), g_action_group_get_action_enabled(), -g_action_group_get_action_parameter_type(), -g_action_group_get_action_state_type(), -g_action_group_get_action_state_hint() and -g_action_group_get_action_state() with a single function call. - -This provides two main benefits. - -The first is the improvement in efficiency that comes with not having -to perform repeated lookups of the action in order to discover -different things about it. The second is that implementing -#GActionGroup can now be done by only overriding this one virtual -function. - -The interface provides a default implementation of this function that -calls the individual functions, as required, to fetch the -information. The interface also provides default implementations of -those functions that call this function. All implementations, -therefore, must override either this function or all of the others. - -If the action exists, %TRUE is returned and any of the requested -fields (as indicated by having a non-%NULL reference passed in) are -filled. If the action doesn't exist, %FALSE is returned and the -fields may or may not have been modified. - - - %TRUE if the action exists, else %FALSE - - - - - a #GActionGroup - - - - the name of an action in the group - - - - if the action is presently enabled - - - - the parameter type, or %NULL if none needed - - - - the state type, or %NULL if stateless - - - - the state hint, or %NULL if none - - - - the current state, or %NULL if stateless - - - - - - Signals that a new action was just added to the group. -This signal is emitted after the action has been added -and is now visible. - - - - - - the name of the action in @action_group - - - - - - Signals that the enabled status of the named action has changed. - - - - - - the name of the action in @action_group - - - - whether the action is enabled or not - - - - - - Signals that an action is just about to be removed from the group. -This signal is emitted before the action is removed, so the action -is still visible and can be queried from the signal handler. - - - - - - the name of the action in @action_group - - - - - - Signals that the state of the named action has changed. - - - - - - the name of the action in @action_group - - - - the new value of the state - - - - - - - The virtual function table for #GActionGroup. - - - - - - - - - whether the named action exists - - - - - a #GActionGroup - - - - the name of the action to check for - - - - - - - - - - a %NULL-terminated array of the names of the -actions in the group - - - - - - - a #GActionGroup - - - - - - - - - - whether or not the action is currently enabled - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - - - - - the parameter type - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - - - - - the state type, if the action is stateful - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - - - - - the state range hint - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - - - - - the current state of the action - - - - - a #GActionGroup - - - - the name of the action to query - - - - - - - - - - - - - - a #GActionGroup - - - - the name of the action to request the change on - - - - the new state - - - - - - - - - - - - - - a #GActionGroup - - - - the name of the action to activate - - - - parameters to the activation - - - - - - - - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - - - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - - - - - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - whether or not the action is now enabled - - - - - - - - - - - - - - a #GActionGroup - - - - the name of an action in the group - - - - the new state of the named action - - - - - - - - - - %TRUE if the action exists, else %FALSE - - - - - a #GActionGroup - - - - the name of an action in the group - - - - if the action is presently enabled - - - - the parameter type, or %NULL if none needed - - - - the state type, or %NULL if stateless - - - - the state hint, or %NULL if none - - - - the current state, or %NULL if stateless - - - - - - - - The virtual function table for #GAction. - - - - - - - - - the name of the action - - - - - a #GAction - - - - - - - - - - the parameter type - - - - - a #GAction - - - - - - - - - - the state type, if the action is stateful - - - - - a #GAction - - - - - - - - - - the state range hint - - - - - a #GAction - - - - - - - - - - whether the action is enabled - - - - - a #GAction - - - - - - - - - - the current state of the action - - - - - a #GAction - - - - - - - - - - - - - - a #GAction - - - - the new state - - - - - - - - - - - - - - a #GAction - - - - the parameter to the activation - - - - - - - - The GActionMap interface is implemented by #GActionGroup -implementations that operate by containing a number of -named #GAction instances, such as #GSimpleActionGroup. - -One useful application of this interface is to map the -names of actions from various action groups to unique, -prefixed names (e.g. by prepending "app." or "win."). -This is the motivation for the 'Map' part of the interface -name. - - - Adds an action to the @action_map. - -If the action map already contains an action with the same name -as @action then the old action is dropped from the action map. - -The action map takes its own reference on @action. - - - - - - - a #GActionMap - - - - a #GAction - - - - - - Looks up the action with the name @action_name in @action_map. - -If no such action exists, returns %NULL. - - - a #GAction, or %NULL - - - - - a #GActionMap - - - - the name of an action - - - - - - Removes the named action from the action map. - -If no action of this name is in the map then nothing happens. - - - - - - - a #GActionMap - - - - the name of the action - - - - - - Adds an action to the @action_map. - -If the action map already contains an action with the same name -as @action then the old action is dropped from the action map. - -The action map takes its own reference on @action. - - - - - - - a #GActionMap - - - - a #GAction - - - - - - A convenience function for creating multiple #GSimpleAction instances -and adding them to a #GActionMap. - -Each action is constructed as per one #GActionEntry. - -|[<!-- language="C" --> -static void -activate_quit (GSimpleAction *simple, - GVariant *parameter, - gpointer user_data) -{ - exit (0); -} - -static void -activate_print_string (GSimpleAction *simple, - GVariant *parameter, - gpointer user_data) -{ - g_print ("%s\n", g_variant_get_string (parameter, NULL)); -} - -static GActionGroup * -create_action_group (void) -{ - const GActionEntry entries[] = { - { "quit", activate_quit }, - { "print-string", activate_print_string, "s" } - }; - GSimpleActionGroup *group; - - group = g_simple_action_group_new (); - g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); - - return G_ACTION_GROUP (group); -} -]| - - - - - - - a #GActionMap - - - - a pointer to - the first item in an array of #GActionEntry structs - - - - - - the length of @entries, or -1 if @entries is %NULL-terminated - - - - the user data for signal connections - - - - - - Looks up the action with the name @action_name in @action_map. - -If no such action exists, returns %NULL. - - - a #GAction, or %NULL - - - - - a #GActionMap - - - - the name of an action - - - - - - Removes the named action from the action map. - -If no action of this name is in the map then nothing happens. - - - - - - - a #GActionMap - - - - the name of the action - - - - - - - The virtual function table for #GActionMap. - - - - - - - - - a #GAction, or %NULL - - - - - a #GActionMap - - - - the name of an action - - - - - - - - - - - - - - a #GActionMap - - - - a #GAction - - - - - - - - - - - - - - a #GActionMap - - - - the name of the action - - - - - - - - #GAppInfo and #GAppLaunchContext are used for describing and launching -applications installed on the system. - -As of GLib 2.20, URIs will always be converted to POSIX paths -(using g_file_get_path()) when using g_app_info_launch() even if -the application requested an URI and not a POSIX path. For example -for a desktop-file based application with Exec key `totem -%U` and a single URI, `sftp://foo/file.avi`, then -`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will -only work if a set of suitable GIO extensions (such as gvfs 2.26 -compiled with FUSE support), is available and operational; if this -is not the case, the URI will be passed unmodified to the application. -Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX -path (in gvfs there's no FUSE mount for it); such URIs will be -passed unmodified to the application. - -Specifically for gvfs 2.26 and later, the POSIX URI will be mapped -back to the GIO URI in the #GFile constructors (since gvfs -implements the #GVfs extension point). As such, if the application -needs to examine the URI, it needs to use g_file_get_uri() or -similar on #GFile. In other words, an application cannot assume -that the URI passed to e.g. g_file_new_for_commandline_arg() is -equal to the result of g_file_get_uri(). The following snippet -illustrates this: - -|[ -GFile *f; -char *uri; - -file = g_file_new_for_commandline_arg (uri_from_commandline); - -uri = g_file_get_uri (file); -strcmp (uri, uri_from_commandline) == 0; -g_free (uri); - -if (g_file_has_uri_scheme (file, "cdda")) - { - // do something special with uri - } -g_object_unref (file); -]| - -This code will work when both `cdda://sr0/Track 1.wav` and -`/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the -application. It should be noted that it's generally not safe -for applications to rely on the format of a particular URIs. -Different launcher applications (e.g. file managers) may have -different ideas of what a given URI means. - - - Creates a new #GAppInfo from the given information. - -Note that for @commandline, the quoting rules of the Exec key of the -[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) -are applied. For example, if the @commandline contains -percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. - - - new #GAppInfo for given command. - - - - - the commandline to use - - - - the application name, or %NULL to use @commandline - - - - flags that can specify details of the created #GAppInfo - - - - - - Gets a list of all of the applications currently registered -on this system. - -For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. - - - a newly allocated #GList of references to #GAppInfos. - - - - - - - Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Gets the default #GAppInfo for a given content type. - - - #GAppInfo for given @content_type or - %NULL on error. - - - - - the content type to find a #GAppInfo for - - - - if %TRUE, the #GAppInfo is expected to - support URIs - - - - - - Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - - - #GAppInfo for given @uri_scheme or %NULL on error. - - - - - a string containing a URI scheme. - - - - - - Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. -Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. - -The D-Bus–activated applications don't have to be started if your application -terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. - - - %TRUE on success, %FALSE on error. - - - - - the uri to show - - - - an optional #GAppLaunchContext - - - - - - Async version of g_app_info_launch_default_for_uri(). - -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. - -This is also useful if you want to be sure that the D-Bus–activated -applications are really started before termination and if you are interested -in receiving error information from their activation. - - - - - - - the uri to show - - - - an optional #GAppLaunchContext - - - - a #GCancellable - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - Finishes an asynchronous launch-default-for-uri operation. - - - %TRUE if the launch was successful, %FALSE if @error is set - - - - - a #GAsyncResult - - - - - - Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). - - - - - - - a content type - - - - - - Adds a content type to the application information to indicate the -application is capable of opening files with the given content type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). - - - %TRUE if @appinfo can be deleted - - - - - a #GAppInfo - - - - - - Checks if a supported content type can be removed from an application. - - - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. - - - - - a #GAppInfo. - - - - - - Tries to delete a #GAppInfo. - -On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). - - - %TRUE if @appinfo has been deleted - - - - - a #GAppInfo - - - - - - Creates a duplicate of a #GAppInfo. - - - a duplicate of @appinfo. - - - - - a #GAppInfo. - - - - - - Checks if two #GAppInfos are equal. - -Note that the check <emphasis>may not</emphasis> compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. - - - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. - - - - - the first #GAppInfo. - - - - the second #GAppInfo. - - - - - - - - - - - - - - - - - Gets a human-readable description of an installed application. - - - a string containing a description of the -application @appinfo, or %NULL if none. - - - - - a #GAppInfo. - - - - - - Gets the display name of the application. The display name is often more -descriptive to the user than the name itself. - - - the display name of the application for @appinfo, or the name if -no display name is available. - - - - - a #GAppInfo. - - - - - - - - - - - - - - - - - Gets the icon for the application. - - - the default #GIcon for @appinfo or %NULL -if there is no default icon. - - - - - a #GAppInfo. - - - - - - Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. - -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. - - - a string containing the application's ID. - - - - - a #GAppInfo. - - - - - - Gets the installed name of the application. - - - the name of the application for @appinfo. - - - - - a #GAppInfo. - - - - - - Retrieves the list of content types that @app_info claims to support. -If this information is not provided by the environment, this function -will return %NULL. -This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by -the application. - - - - a list of content types. - - - - - - - a #GAppInfo that can handle files - - - - - - Launches the application. Passes @files to the launched application -as arguments, using the optional @context to get information -about the details of the launcher (like what screen it is on). -On error, @error will be set accordingly. - -To launch the application without arguments pass a %NULL @files list. - -Note that even if the launch is successful the application launched -can fail to start if it runs into problems during startup. There is -no way to detect this. - -Some URIs can be changed when passed through a GFile (for instance -unsupported URIs with strange formats like mailto:), so if you have -a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. - -The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). - -On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` -environment variable with the path of the launched desktop file and -`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched -process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, -should it be inherited by further processes. The `DISPLAY` and -`DESKTOP_STARTUP_ID` environment variables are also set, based -on information provided in @context. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - a #GAppLaunchContext or %NULL - - - - - - Launches the application. This passes the @uris to the launched application -as arguments, using the optional @context to get information -about the details of the launcher (like what screen it is on). -On error, @error will be set accordingly. - -To launch the application without arguments pass a %NULL @uris list. - -Note that even if the launch is successful the application launched -can fail to start if it runs into problems during startup. There is -no way to detect this. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - - - Async version of g_app_info_launch_uris(). - -The @callback is invoked immediately after the application launch, but it -waits for activation in case of D-Bus–activated applications and also provides -extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). - - - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - a #GCancellable - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - Finishes a g_app_info_launch_uris_async() operation. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GAsyncResult - - - - - - Removes a supported type from an application, if possible. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - Sets the application as the default handler for the given file extension. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string containing the file extension - (without the dot). - - - - - - Sets the application as the default handler for a given type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default -application for that content type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - Checks if the application info should be shown in menus that -list available applications. - - - %TRUE if the @appinfo should be shown, %FALSE otherwise. - - - - - a #GAppInfo. - - - - - - Checks if the application accepts files as arguments. - - - %TRUE if the @appinfo supports files. - - - - - a #GAppInfo. - - - - - - Checks if the application supports reading files and directories from URIs. - - - %TRUE if the @appinfo supports URIs. - - - - - a #GAppInfo. - - - - - - Adds a content type to the application information to indicate the -application is capable of opening files with the given content type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). - - - %TRUE if @appinfo can be deleted - - - - - a #GAppInfo - - - - - - Checks if a supported content type can be removed from an application. - - - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. - - - - - a #GAppInfo. - - - - - - Tries to delete a #GAppInfo. - -On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). - - - %TRUE if @appinfo has been deleted - - - - - a #GAppInfo - - - - - - Creates a duplicate of a #GAppInfo. - - - a duplicate of @appinfo. - - - - - a #GAppInfo. - - - - - - Checks if two #GAppInfos are equal. - -Note that the check <emphasis>may not</emphasis> compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. - - - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. - - - - - the first #GAppInfo. - - - - the second #GAppInfo. - - - - - - Gets the commandline with which the application will be -started. - - - a string containing the @appinfo's commandline, - or %NULL if this information is not available - - - - - a #GAppInfo - - - - - - Gets a human-readable description of an installed application. - - - a string containing a description of the -application @appinfo, or %NULL if none. - - - - - a #GAppInfo. - - - - - - Gets the display name of the application. The display name is often more -descriptive to the user than the name itself. - - - the display name of the application for @appinfo, or the name if -no display name is available. - - - - - a #GAppInfo. - - - - - - Gets the executable's name for the installed application. - - - a string containing the @appinfo's application -binaries name - - - - - a #GAppInfo - - - - - - Gets the icon for the application. - - - the default #GIcon for @appinfo or %NULL -if there is no default icon. - - - - - a #GAppInfo. - - - - - - Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. - -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. - - - a string containing the application's ID. - - - - - a #GAppInfo. - - - - - - Gets the installed name of the application. - - - the name of the application for @appinfo. - - - - - a #GAppInfo. - - - - - - Retrieves the list of content types that @app_info claims to support. -If this information is not provided by the environment, this function -will return %NULL. -This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by -the application. - - - - a list of content types. - - - - - - - a #GAppInfo that can handle files - - - - - - Launches the application. Passes @files to the launched application -as arguments, using the optional @context to get information -about the details of the launcher (like what screen it is on). -On error, @error will be set accordingly. - -To launch the application without arguments pass a %NULL @files list. - -Note that even if the launch is successful the application launched -can fail to start if it runs into problems during startup. There is -no way to detect this. - -Some URIs can be changed when passed through a GFile (for instance -unsupported URIs with strange formats like mailto:), so if you have -a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. - -The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). - -On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` -environment variable with the path of the launched desktop file and -`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched -process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, -should it be inherited by further processes. The `DISPLAY` and -`DESKTOP_STARTUP_ID` environment variables are also set, based -on information provided in @context. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - a #GAppLaunchContext or %NULL - - - - - - Launches the application. This passes the @uris to the launched application -as arguments, using the optional @context to get information -about the details of the launcher (like what screen it is on). -On error, @error will be set accordingly. - -To launch the application without arguments pass a %NULL @uris list. - -Note that even if the launch is successful the application launched -can fail to start if it runs into problems during startup. There is -no way to detect this. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - - - Async version of g_app_info_launch_uris(). - -The @callback is invoked immediately after the application launch, but it -waits for activation in case of D-Bus–activated applications and also provides -extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). - - - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - a #GCancellable - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - Finishes a g_app_info_launch_uris_async() operation. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GAsyncResult - - - - - - Removes a supported type from an application, if possible. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - Sets the application as the default handler for the given file extension. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string containing the file extension - (without the dot). - - - - - - Sets the application as the default handler for a given type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default -application for that content type. - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - Checks if the application info should be shown in menus that -list available applications. - - - %TRUE if the @appinfo should be shown, %FALSE otherwise. - - - - - a #GAppInfo. - - - - - - Checks if the application accepts files as arguments. - - - %TRUE if the @appinfo supports files. - - - - - a #GAppInfo. - - - - - - Checks if the application supports reading files and directories from URIs. - - - %TRUE if the @appinfo supports URIs. - - - - - a #GAppInfo. - - - - - - - Flags used when creating a #GAppInfo. - - No flags. - - - Application opens in a terminal window. - - - Application supports URI arguments. - - - Application supports startup notification. Since 2.26 - - - - Application Information interface, for operating system portability. - - - The parent interface. - - - - - - - a duplicate of @appinfo. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. - - - - - the first #GAppInfo. - - - - the second #GAppInfo. - - - - - - - - - - a string containing the application's ID. - - - - - a #GAppInfo. - - - - - - - - - - the name of the application for @appinfo. - - - - - a #GAppInfo. - - - - - - - - - - a string containing a description of the -application @appinfo, or %NULL if none. - - - - - a #GAppInfo. - - - - - - - - - - - - - - - - - - - - - - - the default #GIcon for @appinfo or %NULL -if there is no default icon. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - a #GAppLaunchContext or %NULL - - - - - - - - - - %TRUE if the @appinfo supports URIs. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE if the @appinfo supports files. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - - - - - - - %TRUE if the @appinfo should be shown, %FALSE otherwise. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - - - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string containing the file extension - (without the dot). - - - - - - - - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - - - - - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - a string. - - - - - - - - - - %TRUE if @appinfo can be deleted - - - - - a #GAppInfo - - - - - - - - - - %TRUE if @appinfo has been deleted - - - - - a #GAppInfo - - - - - - - - - - - - - - - - - - - - - - - the display name of the application for @appinfo, or the name if -no display name is available. - - - - - a #GAppInfo. - - - - - - - - - - %TRUE on success, %FALSE on error. - - - - - a #GAppInfo. - - - - the content type. - - - - - - - - - - - a list of content types. - - - - - - - a #GAppInfo that can handle files - - - - - - - - - - - - - - a #GAppInfo - - - - a #GList containing URIs to launch. - - - - - - a #GAppLaunchContext or %NULL - - - - a #GCancellable - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - - - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GAppInfo - - - - a #GAsyncResult - - - - - - - - #GAppInfoMonitor is a very simple object used for monitoring the app -info database for changes (ie: newly installed or removed -applications). - -Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect -to the "changed" signal. - -In the usual case, applications should try to make note of the change -(doing things like invalidating caches) but not act on it. In -particular, applications should avoid making calls to #GAppInfo APIs -in response to the change signal, deferring these until the time that -the data is actually required. The exception to this case is when -application information is actually being displayed on the screen -(eg: during a search or when the list of all applications is shown). -The reason for this is that changes to the list of installed -applications often come in groups (like during system updates) and -rescanning the list on every change is pointless and expensive. - - Gets the #GAppInfoMonitor for the current thread-default main -context. - -The #GAppInfoMonitor will emit a "changed" signal in the -thread-default main context whenever the list of installed -applications (as reported by g_app_info_get_all()) may have changed. - -You must only call g_object_unref() on the return value from under -the same main context as you created it. - - - a reference to a #GAppInfoMonitor - - - - - Signal emitted when the app info database for changes (ie: newly installed -or removed applications). - - - - - - - Integrating the launch with the launching application. This is used to -handle for instance startup notification and launching the new application -on the same screen as the launching window. - - - Creates a new application launch context. This is not normally used, -instead you instantiate a subclass of this, such as #GdkAppLaunchContext. - - - a #GAppLaunchContext. - - - - - Gets the display string for the @context. This is used to ensure new -applications are started on the same display as the launching -application, by setting the `DISPLAY` environment variable. - - - a display string for the display. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - - - Initiates startup notification for the application and returns the -`DESKTOP_STARTUP_ID` for the launched operation, if supported. - -Startup notification IDs are defined in the -[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - - - a startup notification ID for the application, or %NULL if - not supported. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of of #GFile objects - - - - - - - - Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). - - - - - - - a #GAppLaunchContext. - - - - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). - - - - - - - - - - - - - - - - - - - - - - - Gets the display string for the @context. This is used to ensure new -applications are started on the same display as the launching -application, by setting the `DISPLAY` environment variable. - - - a display string for the display. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - - - Gets the complete environment variable list to be passed to -the child process when @context is used to launch an application. -This is a %NULL-terminated array of strings, where each string has -the form `KEY=VALUE`. - - - - the child's environment - - - - - - - a #GAppLaunchContext - - - - - - Initiates startup notification for the application and returns the -`DESKTOP_STARTUP_ID` for the launched operation, if supported. - -Startup notification IDs are defined in the -[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - - - a startup notification ID for the application, or %NULL if - not supported. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of of #GFile objects - - - - - - - - Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). - - - - - - - a #GAppLaunchContext. - - - - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). - - - - - - Arranges for @variable to be set to @value in the child's -environment when @context is used to launch an application. - - - - - - - a #GAppLaunchContext - - - - the environment variable to set - - - - the value for to set the variable to. - - - - - - Arranges for @variable to be unset in the child's environment -when @context is used to launch an application. - - - - - - - a #GAppLaunchContext - - - - the environment variable to remove - - - - - - - - - - - - The ::launch-failed signal is emitted when a #GAppInfo launch -fails. The startup notification id is provided, so that the launcher -can cancel the startup notification. - - - - - - the startup notification id for the failed launch - - - - - - The ::launched signal is emitted when a #GAppInfo is successfully -launched. The @platform_data is an GVariant dictionary mapping -strings to variants (ie a{sv}), which contains additional, -platform-specific data about this launch. On UNIX, at least the -"pid" and "startup-notification-id" keys will be present. - - - - - - the #GAppInfo that was just launched - - - - additional platform-specific data for this launch - - - - - - - - - - - - - - - a display string for the display. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of #GFile objects - - - - - - - - - - - - a startup notification ID for the application, or %NULL if - not supported. - - - - - a #GAppLaunchContext - - - - a #GAppInfo - - - - a #GList of of #GFile objects - - - - - - - - - - - - - - - - a #GAppLaunchContext. - - - - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GApplication is the foundation of an application. It wraps some -low-level platform-specific services and is intended to act as the -foundation for higher-level application classes such as -#GtkApplication or #MxApplication. In general, you should not use -this class outside of a higher level framework. - -GApplication provides convenient life cycle management by maintaining -a "use count" for the primary application instance. The use count can -be changed using g_application_hold() and g_application_release(). If -it drops to zero, the application exits. Higher-level classes such as -#GtkApplication employ the use count to ensure that the application -stays alive as long as it has any opened windows. - -Another feature that GApplication (optionally) provides is process -uniqueness. Applications can make use of this functionality by -providing a unique application ID. If given, only one application -with this ID can be running at a time per session. The session -concept is platform-dependent, but corresponds roughly to a graphical -desktop login. When your application is launched again, its -arguments are passed through platform communication to the already -running program. The already running instance of the program is -called the "primary instance"; for non-unique applications this is -the always the current instance. On Linux, the D-Bus session bus -is used for communication. - -The use of #GApplication differs from some other commonly-used -uniqueness libraries (such as libunique) in important ways. The -application is not expected to manually register itself and check -if it is the primary instance. Instead, the main() function of a -#GApplication should do very little more than instantiating the -application instance, possibly connecting signal handlers, then -calling g_application_run(). All checks for uniqueness are done -internally. If the application is the primary instance then the -startup signal is emitted and the mainloop runs. If the application -is not the primary instance then a signal is sent to the primary -instance and g_application_run() promptly returns. See the code -examples below. - -If used, the expected form of an application identifier is the same as -that of of a -[D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). -Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, -`org._7_zip.Archiver`. -For details on valid application identifiers, see g_application_id_is_valid(). - -On Linux, the application identifier is claimed as a well-known bus name -on the user's session bus. This means that the uniqueness of your -application is scoped to the current session. It also means that your -application may provide additional services (through registration of other -object paths) at that bus name. The registration of these object paths -should be done with the shared GDBus session bus. Note that due to the -internal architecture of GDBus, method calls can be dispatched at any time -(even if a main loop is not running). For this reason, you must ensure that -any object paths that you wish to register are registered before #GApplication -attempts to acquire the bus name of your application (which happens in -g_application_register()). Unfortunately, this means that you cannot use -g_application_get_is_remote() to decide if you want to register object paths. - -GApplication also implements the #GActionGroup and #GActionMap -interfaces and lets you easily export actions by adding them with -g_action_map_add_action(). When invoking an action by calling -g_action_group_activate_action() on the application, it is always -invoked in the primary instance. The actions are also exported on -the session bus, and GIO provides the #GDBusActionGroup wrapper to -conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper -for remote access to exported #GMenuModels. - -There is a number of different entry points into a GApplication: - -- via 'Activate' (i.e. just starting the application) - -- via 'Open' (i.e. opening some files) - -- by handling a command-line - -- via activating an action - -The #GApplication::startup signal lets you handle the application -initialization for all of these in a single place. - -Regardless of which of these entry points is used to start the -application, GApplication passes some ‘platform data’ from the -launching instance to the primary instance, in the form of a -#GVariant dictionary mapping strings to variants. To use platform -data, override the @before_emit or @after_emit virtual functions -in your #GApplication subclass. When dealing with -#GApplicationCommandLine objects, the platform data is -directly available via g_application_command_line_get_cwd(), -g_application_command_line_get_environ() and -g_application_command_line_get_platform_data(). - -As the name indicates, the platform data may vary depending on the -operating system, but it always includes the current directory (key -"cwd"), and optionally the environment (ie the set of environment -variables and their values) of the calling process (key "environ"). -The environment is only added to the platform data if the -%G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses -can add their own platform data by overriding the @add_platform_data -virtual function. For instance, #GtkApplication adds startup notification -data in this way. - -To parse commandline arguments you may handle the -#GApplication::command-line signal or override the local_command_line() -vfunc, to parse them in either the primary instance or the local instance, -respectively. - -For an example of opening files with a GApplication, see -[gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). - -For an example of using actions with GApplication, see -[gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). - -For an example of using extra D-Bus hooks with GApplication, see -[gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). - - - - - Creates a new #GApplication instance. - -If non-%NULL, the application id must be valid. See -g_application_id_is_valid(). - -If no application ID is given then some features of #GApplication -(most notably application uniqueness) will be disabled. - - - a new #GApplication instance - - - - - the application id - - - - the application flags - - - - - - Returns the default #GApplication instance for this process. - -Normally there is only one #GApplication per process and it becomes -the default when it is created. You can exercise more control over -this by using g_application_set_default(). - -If there is no default application then %NULL is returned. - - - the default application for this process, or %NULL - - - - - Checks if @application_id is a valid application identifier. - -A valid ID is required for calls to g_application_new() and -g_application_set_application_id(). - -Application identifiers follow the same format as -[D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). -For convenience, the restrictions on application identifiers are -reproduced here: - -- Application identifiers are composed of 1 or more elements separated by a - period (`.`) character. All elements must contain at least one character. - -- Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`, - with `-` discouraged in new application identifiers. Each element must not - begin with a digit. - -- Application identifiers must contain at least one `.` (period) character - (and thus at least two elements). - -- Application identifiers must not begin with a `.` (period) character. - -- Application identifiers must not exceed 255 characters. - -Note that the hyphen (`-`) character is allowed in application identifiers, -but is problematic or not allowed in various specifications and APIs that -refer to D-Bus, such as -[Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers), -the -[`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus), -and the convention that an application's "main" interface and object path -resemble its application identifier and bus name. To avoid situations that -require special-case handling, it is recommended that new application -identifiers consistently replace hyphens with underscores. - -Like D-Bus interface names, application identifiers should start with the -reversed DNS domain name of the author of the interface (in lower-case), and -it is conventional for the rest of the application identifier to consist of -words run together, with initial capital letters. - -As with D-Bus interface names, if the author's DNS domain name contains -hyphen/minus characters they should be replaced by underscores, and if it -contains leading digits they should be escaped by prepending an underscore. -For example, if the owner of 7-zip.org used an application identifier for an -archiving application, it might be named `org._7_zip.Archiver`. - - - %TRUE if @application_id is valid - - - - - a potential application identifier - - - - - - Activates the application. - -In essence, this results in the #GApplication::activate signal being -emitted in the primary instance. - -The application must be registered before calling this function. - - - - - - - a #GApplication - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This virtual function is always invoked in the local instance. It -gets passed a pointer to a %NULL-terminated copy of @argv and is -expected to remove arguments that it handled (shifting up remaining -arguments). - -The last argument to local_command_line() is a pointer to the @status -variable which can used to set the exit status that is returned from -g_application_run(). - -See g_application_run() for more details on #GApplication startup. - - - %TRUE if the commandline has been completely handled - - - - - a #GApplication - - - - array of command line arguments - - - - - - exit status to fill after processing the command line. - - - - - - - - - - - - - - - - - Opens the given files. - -In essence, this results in the #GApplication::open signal being emitted -in the primary instance. - -@n_files must be greater than zero. - -@hint is simply passed through to the ::open signal. It is -intended to be used by applications that have multiple modes for -opening files (eg: "view" vs "edit", etc). Unless you have a need -for this functionality, you should use "". - -The application must be registered before calling this function -and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - - - - - - - a #GApplication - - - - an array of #GFiles to open - - - - - - the length of the @files array - - - - a hint (or ""), but never %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Activates the application. - -In essence, this results in the #GApplication::activate signal being -emitted in the primary instance. - -The application must be registered before calling this function. - - - - - - - a #GApplication - - - - - - Add an option to be handled by @application. - -Calling this function is the equivalent of calling -g_application_add_main_option_entries() with a single #GOptionEntry -that has its arg_data member set to %NULL. - -The parsed arguments will be packed into a #GVariantDict which -is passed to #GApplication::handle-local-options. If -%G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also -be sent to the primary instance. See -g_application_add_main_option_entries() for more details. - -See #GOptionEntry for more documentation of the arguments. - - - - - - - the #GApplication - - - - the long name of an option used to specify it in a commandline - - - - the short name of an option - - - - flags from #GOptionFlags - - - - the type of the option, as a #GOptionArg - - - - the description for the option in `--help` output - - - - the placeholder to use for the extra argument - parsed by the option in `--help` output - - - - - - Adds main option entries to be handled by @application. - -This function is comparable to g_option_context_add_main_entries(). - -After the commandline arguments are parsed, the -#GApplication::handle-local-options signal will be emitted. At this -point, the application can inspect the values pointed to by @arg_data -in the given #GOptionEntrys. - -Unlike #GOptionContext, #GApplication supports giving a %NULL -@arg_data for a non-callback #GOptionEntry. This results in the -argument in question being packed into a #GVariantDict which is also -passed to #GApplication::handle-local-options, where it can be -inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is -set, then the resulting dictionary is sent to the primary instance, -where g_application_command_line_get_options_dict() will return it. -This "packing" is done according to the type of the argument -- -booleans for normal flags, strings for strings, bytestrings for -filenames, etc. The packing only occurs if the flag is given (ie: we -do not pack a "false" #GVariant in the case that a flag is missing). - -In general, it is recommended that all commandline arguments are -parsed locally. The options dictionary should then be used to -transmit the result of the parsing to the primary instance, where -g_variant_dict_lookup() can be used. For local options, it is -possible to either use @arg_data in the usual way, or to consult (and -potentially remove) the option from the options dictionary. - -This function is new in GLib 2.40. Before then, the only real choice -was to send all of the commandline arguments (options and all) to the -primary instance for handling. #GApplication ignored them completely -on the local side. Calling this function "opts in" to the new -behaviour, and in particular, means that unrecognised options will be -treated as errors. Unrecognised options have never been ignored when -%G_APPLICATION_HANDLES_COMMAND_LINE is unset. - -If #GApplication::handle-local-options needs to see the list of -filenames, then the use of %G_OPTION_REMAINING is recommended. If -@arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into -the options dictionary. If you do use %G_OPTION_REMAINING then you -need to handle these arguments for yourself because once they are -consumed, they will no longer be visible to the default handling -(which treats them as filenames to be opened). - -It is important to use the proper GVariant format when retrieving -the options with g_variant_dict_lookup(): -- for %G_OPTION_ARG_NONE, use `b` -- for %G_OPTION_ARG_STRING, use `&s` -- for %G_OPTION_ARG_INT, use `i` -- for %G_OPTION_ARG_INT64, use `x` -- for %G_OPTION_ARG_DOUBLE, use `d` -- for %G_OPTION_ARG_FILENAME, use `^&ay` -- for %G_OPTION_ARG_STRING_ARRAY, use `^a&s` -- for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay` - - - - - - - a #GApplication - - - - a - %NULL-terminated list of #GOptionEntrys - - - - - - - - Adds a #GOptionGroup to the commandline handling of @application. - -This function is comparable to g_option_context_add_group(). - -Unlike g_application_add_main_option_entries(), this function does -not deal with %NULL @arg_data and never transmits options to the -primary instance. - -The reason for that is because, by the time the options arrive at the -primary instance, it is typically too late to do anything with them. -Taking the GTK option group as an example: GTK will already have been -initialised by the time the #GApplication::command-line handler runs. -In the case that this is not the first-running instance of the -application, the existing instance may already have been running for -a very long time. - -This means that the options from #GOptionGroup are only really usable -in the case that the instance of the application being run is the -first instance. Passing options like `--display=` or `--gdk-debug=` -on future runs will have no effect on the existing primary instance. - -Calling this function will cause the options in the supplied option -group to be parsed, but it does not cause you to be "opted in" to the -new functionality whereby unrecognised options are rejected even if -%G_APPLICATION_HANDLES_COMMAND_LINE was given. - - - - - - - the #GApplication - - - - a #GOptionGroup - - - - - - Marks @application as busy (see g_application_mark_busy()) while -@property on @object is %TRUE. - -The binding holds a reference to @application while it is active, but -not to @object. Instead, the binding is destroyed when @object is -finalized. - - - - - - - a #GApplication - - - - a #GObject - - - - the name of a boolean property of @object - - - - - - Gets the unique identifier for @application. - - - the identifier for @application, owned by @application - - - - - a #GApplication - - - - - - Gets the #GDBusConnection being used by the application, or %NULL. - -If #GApplication is using its D-Bus backend then this function will -return the #GDBusConnection being used for uniqueness and -communication with the desktop environment and other instances of the -application. - -If #GApplication is not using D-Bus then this function will return -%NULL. This includes the situation where the D-Bus backend would -normally be in use but we were unable to connect to the bus. - -This function must not be called before the application has been -registered. See g_application_get_is_registered(). - - - a #GDBusConnection, or %NULL - - - - - a #GApplication - - - - - - Gets the D-Bus object path being used by the application, or %NULL. - -If #GApplication is using its D-Bus backend then this function will -return the D-Bus object path that #GApplication is using. If the -application is the primary instance then there is an object published -at this path. If the application is not the primary instance then -the result of this function is undefined. - -If #GApplication is not using D-Bus then this function will return -%NULL. This includes the situation where the D-Bus backend would -normally be in use but we were unable to connect to the bus. - -This function must not be called before the application has been -registered. See g_application_get_is_registered(). - - - the object path, or %NULL - - - - - a #GApplication - - - - - - Gets the flags for @application. - -See #GApplicationFlags. - - - the flags for @application - - - - - a #GApplication - - - - - - Gets the current inactivity timeout for the application. - -This is the amount of time (in milliseconds) after the last call to -g_application_release() before the application stops running. - - - the timeout, in milliseconds - - - - - a #GApplication - - - - - - Gets the application's current busy state, as set through -g_application_mark_busy() or g_application_bind_busy_property(). - - - %TRUE if @application is currenty marked as busy - - - - - a #GApplication - - - - - - Checks if @application is registered. - -An application is registered if g_application_register() has been -successfully called. - - - %TRUE if @application is registered - - - - - a #GApplication - - - - - - Checks if @application is remote. - -If @application is remote then it means that another instance of -application already exists (the 'primary' instance). Calls to -perform actions on @application will result in the actions being -performed by the primary instance. - -The value of this property cannot be accessed before -g_application_register() has been called. See -g_application_get_is_registered(). - - - %TRUE if @application is remote - - - - - a #GApplication - - - - - - Gets the resource base path of @application. - -See g_application_set_resource_base_path() for more information. - - - the base resource path, if one is set - - - - - a #GApplication - - - - - - Increases the use count of @application. - -Use this function to indicate that the application has a reason to -continue to run. For example, g_application_hold() is called by GTK+ -when a toplevel window is on the screen. - -To cancel the hold, call g_application_release(). - - - - - - - a #GApplication - - - - - - Increases the busy count of @application. - -Use this function to indicate that the application is busy, for instance -while a long running operation is pending. - -The busy state will be exposed to other processes, so a session shell will -use that information to indicate the state to the user (e.g. with a -spinner). - -To cancel the busy indication, use g_application_unmark_busy(). - - - - - - - a #GApplication - - - - - - Opens the given files. - -In essence, this results in the #GApplication::open signal being emitted -in the primary instance. - -@n_files must be greater than zero. - -@hint is simply passed through to the ::open signal. It is -intended to be used by applications that have multiple modes for -opening files (eg: "view" vs "edit", etc). Unless you have a need -for this functionality, you should use "". - -The application must be registered before calling this function -and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - - - - - - - a #GApplication - - - - an array of #GFiles to open - - - - - - the length of the @files array - - - - a hint (or ""), but never %NULL - - - - - - Immediately quits the application. - -Upon return to the mainloop, g_application_run() will return, -calling only the 'shutdown' function before doing so. - -The hold count is ignored. -Take care if your code has called g_application_hold() on the application and -is therefore still expecting it to exist. -(Note that you may have called g_application_hold() indirectly, for example -through gtk_application_add_window().) - -The result of calling g_application_run() again after it returns is -unspecified. - - - - - - - a #GApplication - - - - - - Attempts registration of the application. - -This is the point at which the application discovers if it is the -primary instance or merely acting as a remote for an already-existing -primary instance. This is implemented by attempting to acquire the -application identifier as a unique bus name on the session bus using -GDBus. - -If there is no application ID or if %G_APPLICATION_NON_UNIQUE was -given, then this process will always become the primary instance. - -Due to the internal architecture of GDBus, method calls can be -dispatched at any time (even if a main loop is not running). For -this reason, you must ensure that any object paths that you wish to -register are registered before calling this function. - -If the application has already been registered then %TRUE is -returned with no work performed. - -The #GApplication::startup signal is emitted if registration succeeds -and @application is the primary instance (including the non-unique -case). - -In the event of an error (such as @cancellable being cancelled, or a -failure to connect to the session bus), %FALSE is returned and @error -is set appropriately. - -Note: the return value of this function is not an indicator that this -instance is or is not the primary instance of the application. See -g_application_get_is_remote() for that. - - - %TRUE if registration succeeded - - - - - a #GApplication - - - - a #GCancellable, or %NULL - - - - - - Decrease the use count of @application. - -When the use count reaches zero, the application will stop running. - -Never call this function except to cancel the effect of a previous -call to g_application_hold(). - - - - - - - a #GApplication - - - - - - Runs the application. - -This function is intended to be run from main() and its return value -is intended to be returned by main(). Although you are expected to pass -the @argc, @argv parameters from main() to this function, it is possible -to pass %NULL if @argv is not available or commandline handling is not -required. Note that on Windows, @argc and @argv are ignored, and -g_win32_get_command_line() is called internally (for proper support -of Unicode commandline arguments). - -#GApplication will attempt to parse the commandline arguments. You -can add commandline flags to the list of recognised options by way of -g_application_add_main_option_entries(). After this, the -#GApplication::handle-local-options signal is emitted, from which the -application can inspect the values of its #GOptionEntrys. - -#GApplication::handle-local-options is a good place to handle options -such as `--version`, where an immediate reply from the local process is -desired (instead of communicating with an already-running instance). -A #GApplication::handle-local-options handler can stop further processing -by returning a non-negative value, which then becomes the exit status of -the process. - -What happens next depends on the flags: if -%G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining -commandline arguments are sent to the primary instance, where a -#GApplication::command-line signal is emitted. Otherwise, the -remaining commandline arguments are assumed to be a list of files. -If there are no files listed, the application is activated via the -#GApplication::activate signal. If there are one or more files, and -%G_APPLICATION_HANDLES_OPEN was specified then the files are opened -via the #GApplication::open signal. - -If you are interested in doing more complicated local handling of the -commandline then you should implement your own #GApplication subclass -and override local_command_line(). In this case, you most likely want -to return %TRUE from your local_command_line() implementation to -suppress the default handling. See -[gapplication-example-cmdline2.c][gapplication-example-cmdline2] -for an example. - -If, after the above is done, the use count of the application is zero -then the exit status is returned immediately. If the use count is -non-zero then the default main context is iterated until the use count -falls to zero, at which point 0 is returned. - -If the %G_APPLICATION_IS_SERVICE flag is set, then the service will -run for as much as 10 seconds with a use count of zero while waiting -for the message that caused the activation to arrive. After that, -if the use count falls to zero the application will exit immediately, -except in the case that g_application_set_inactivity_timeout() is in -use. - -This function sets the prgname (g_set_prgname()), if not already set, -to the basename of argv[0]. - -Much like g_main_loop_run(), this function will acquire the main context -for the duration that the application is running. - -Since 2.40, applications that are not explicitly flagged as services -or launchers (ie: neither %G_APPLICATION_IS_SERVICE or -%G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the -default handler for local_command_line) if "--gapplication-service" -was given in the command line. If this flag is present then normal -commandline processing is interrupted and the -%G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" -solution whereby running an application directly from the commandline -will invoke it in the normal way (which can be useful for debugging) -while still allowing applications to be D-Bus activated in service -mode. The D-Bus service file should invoke the executable with -"--gapplication-service" as the sole commandline argument. This -approach is suitable for use by most graphical applications but -should not be used from applications like editors that need precise -control over when processes invoked via the commandline will exit and -what their exit status will be. - - - the exit status - - - - - a #GApplication - - - - the argc from main() (or 0 if @argv is %NULL) - - - - - the argv from main(), or %NULL - - - - - - - - Sends a notification on behalf of @application to the desktop shell. -There is no guarantee that the notification is displayed immediately, -or even at all. - -Notifications may persist after the application exits. It will be -D-Bus-activated when the notification or one of its actions is -activated. - -Modifying @notification after this call has no effect. However, the -object can be reused for a later call to this function. - -@id may be any string that uniquely identifies the event for the -application. It does not need to be in any special format. For -example, "new-message" might be appropriate for a notification about -new messages. - -If a previous notification was sent with the same @id, it will be -replaced with @notification and shown again as if it was a new -notification. This works even for notifications sent from a previous -execution of the application, as long as @id is the same string. - -@id may be %NULL, but it is impossible to replace or withdraw -notifications without an id. - -If @notification is no longer relevant, it can be withdrawn with -g_application_withdraw_notification(). - - - - - - - a #GApplication - - - - id of the notification, or %NULL - - - - the #GNotification to send - - - - - - This used to be how actions were associated with a #GApplication. -Now there is #GActionMap for that. - Use the #GActionMap interface instead. Never ever -mix use of this API with use of #GActionMap on the same @application -or things will go very badly wrong. This function is known to -introduce buggy behaviour (ie: signals not emitted on changes to the -action group), so you should really use #GActionMap instead. - - - - - - - a #GApplication - - - - a #GActionGroup, or %NULL - - - - - - Sets the unique identifier for @application. - -The application id can only be modified if @application has not yet -been registered. - -If non-%NULL, the application id must be valid. See -g_application_id_is_valid(). - - - - - - - a #GApplication - - - - the identifier for @application - - - - - - Sets or unsets the default application for the process, as returned -by g_application_get_default(). - -This function does not take its own reference on @application. If -@application is destroyed then the default application will revert -back to %NULL. - - - - - - - the application to set as default, or %NULL - - - - - - Sets the flags for @application. - -The flags can only be modified if @application has not yet been -registered. - -See #GApplicationFlags. - - - - - - - a #GApplication - - - - the flags for @application - - - - - - Sets the current inactivity timeout for the application. - -This is the amount of time (in milliseconds) after the last call to -g_application_release() before the application stops running. - -This call has no side effects of its own. The value set here is only -used for next time g_application_release() drops the use count to -zero. Any timeouts currently in progress are not impacted. - - - - - - - a #GApplication - - - - the timeout, in milliseconds - - - - - - Adds a description to the @application option context. - -See g_option_context_set_description() for more information. - - - - - - - the #GApplication - - - - a string to be shown in `--help` output - after the list of options, or %NULL - - - - - - Sets the parameter string to be used by the commandline handling of @application. - -This function registers the argument to be passed to g_option_context_new() -when the internal #GOptionContext of @application is created. - -See g_option_context_new() for more information about @parameter_string. - - - - - - - the #GApplication - - - - a string which is displayed - in the first line of `--help` output, after the usage summary `programname [OPTION...]`. - - - - - - Adds a summary to the @application option context. - -See g_option_context_set_summary() for more information. - - - - - - - the #GApplication - - - - a string to be shown in `--help` output - before the list of options, or %NULL - - - - - - Sets (or unsets) the base resource path of @application. - -The path is used to automatically load various [application -resources][gresource] such as menu layouts and action descriptions. -The various types of resources will be found at fixed names relative -to the given base path. - -By default, the resource base path is determined from the application -ID by prefixing '/' and replacing each '.' with '/'. This is done at -the time that the #GApplication object is constructed. Changes to -the application ID after that point will not have an impact on the -resource base path. - -As an example, if the application has an ID of "org.example.app" then -the default resource base path will be "/org/example/app". If this -is a #GtkApplication (and you have not manually changed the path) -then Gtk will then search for the menus of the application at -"/org/example/app/gtk/menus.ui". - -See #GResource for more information about adding resources to your -application. - -You can disable automatic resource loading functionality by setting -the path to %NULL. - -Changing the resource base path once the application is running is -not recommended. The point at which the resource path is consulted -for forming paths for various purposes is unspecified. When writing -a sub-class of #GApplication you should either set the -#GApplication:resource-base-path property at construction time, or call -this function during the instance initialization. Alternatively, you -can call this function in the #GApplicationClass.startup virtual function, -before chaining up to the parent implementation. - - - - - - - a #GApplication - - - - the resource path to use - - - - - - Destroys a binding between @property and the busy state of -@application that was previously created with -g_application_bind_busy_property(). - - - - - - - a #GApplication - - - - a #GObject - - - - the name of a boolean property of @object - - - - - - Decreases the busy count of @application. - -When the busy count reaches zero, the new state will be propagated -to other processes. - -This function must only be called to cancel the effect of a previous -call to g_application_mark_busy(). - - - - - - - a #GApplication - - - - - - Withdraws a notification that was sent with -g_application_send_notification(). - -This call does nothing if a notification with @id doesn't exist or -the notification was never sent. - -This function works even for notifications sent in previous -executions of this application, as long @id is the same as it was for -the sent notification. - -Note that notifications are dismissed when the user clicks on one -of the buttons in a notification or triggers its default action, so -there is no need to explicitly withdraw the notification in that case. - - - - - - - a #GApplication - - - - id of a previously sent notification - - - - - - - - - - - - - - - - - - Whether the application is currently marked as busy through -g_application_mark_busy() or g_application_bind_busy_property(). - - - - - - - - - - - - - - - - - - - The ::activate signal is emitted on the primary instance when an -activation occurs. See g_application_activate(). - - - - - - The ::command-line signal is emitted on the primary instance when -a commandline is not handled locally. See g_application_run() and -the #GApplicationCommandLine documentation for more information. - - An integer that is set as the exit status for the calling - process. See g_application_command_line_set_exit_status(). - - - - - a #GApplicationCommandLine representing the - passed commandline - - - - - - The ::handle-local-options signal is emitted on the local instance -after the parsing of the commandline options has occurred. - -You can add options to be recognised during commandline option -parsing using g_application_add_main_option_entries() and -g_application_add_option_group(). - -Signal handlers can inspect @options (along with values pointed to -from the @arg_data of an installed #GOptionEntrys) in order to -decide to perform certain actions, including direct local handling -(which may be useful for options like --version). - -In the event that the application is marked -%G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will -send the @options dictionary to the primary instance where it can be -read with g_application_command_line_get_options_dict(). The signal -handler can modify the dictionary before returning, and the -modified dictionary will be sent. - -In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, -"normal processing" will treat the remaining uncollected command -line arguments as filenames or URIs. If there are no arguments, -the application is activated by g_application_activate(). One or -more arguments results in a call to g_application_open(). - -If you want to handle the local commandline arguments for yourself -by converting them to calls to g_application_open() or -g_action_group_activate_action() then you must be sure to register -the application first. You should probably not call -g_application_activate() for yourself, however: just return -1 and -allow the default handler to do it for you. This will ensure that -the `--gapplication-service` switch works properly (i.e. no activation -in that case). - -Note that this signal is emitted from the default implementation of -local_command_line(). If you override that function and don't -chain up then this signal will never be emitted. - -You can override local_command_line() if you need more powerful -capabilities than what is provided here, but this should not -normally be required. - - an exit code. If you have handled your options and want -to exit the process, return a non-negative option, 0 for success, -and a positive value for failure. To continue, return -1 to let -the default option processing continue. - - - - - the options dictionary - - - - - - The ::name-lost signal is emitted only on the registered primary instance -when a new instance has taken over. This can only happen if the application -is using the %G_APPLICATION_ALLOW_REPLACEMENT flag. - -The default handler for this signal calls g_application_quit(). - - %TRUE if the signal has been handled - - - - - The ::open signal is emitted on the primary instance when there are -files to open. See g_application_open() for more information. - - - - - - an array of #GFiles - - - - - - the length of @files - - - - a hint provided by the calling instance - - - - - - The ::shutdown signal is emitted only on the registered primary instance -immediately after the main loop terminates. - - - - - - The ::startup signal is emitted on the primary instance immediately -after registration. See g_application_register(). - - - - - - - Virtual function table for #GApplication. - - - - - - - - - - - - - - - - - - - - - - - - - - a #GApplication - - - - - - - - - - - - - - a #GApplication - - - - an array of #GFiles to open - - - - - - the length of the @files array - - - - a hint (or ""), but never %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the commandline has been completely handled - - - - - a #GApplication - - - - array of command line arguments - - - - - - exit status to fill after processing the command line. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GApplicationCommandLine represents a command-line invocation of -an application. It is created by #GApplication and emitted -in the #GApplication::command-line signal and virtual function. - -The class contains the list of arguments that the program was invoked -with. It is also possible to query if the commandline invocation was -local (ie: the current process is running in direct response to the -invocation) or remote (ie: some other process forwarded the -commandline to this process). - -The GApplicationCommandLine object can provide the @argc and @argv -parameters for use with the #GOptionContext command-line parsing API, -with the g_application_command_line_get_arguments() function. See -[gapplication-example-cmdline3.c][gapplication-example-cmdline3] -for an example. - -The exit status of the originally-invoked process may be set and -messages can be printed to stdout or stderr of that process. The -lifecycle of the originally-invoked process is tied to the lifecycle -of this object (ie: the process exits when the last reference is -dropped). - -The main use for #GApplicationCommandLine (and the -#GApplication::command-line signal) is 'Emacs server' like use cases: -You can set the `EDITOR` environment variable to have e.g. git use -your favourite editor to edit commit messages, and if you already -have an instance of the editor running, the editing will happen -in the running instance, instead of opening a new one. An important -aspect of this use case is that the process that gets started by git -does not return until the editing is done. - -Normally, the commandline is completely handled in the -#GApplication::command-line handler. The launching instance exits -once the signal handler in the primary instance has returned, and -the return value of the signal handler becomes the exit status -of the launching instance. -|[<!-- language="C" --> -static int -command_line (GApplication *application, - GApplicationCommandLine *cmdline) -{ - gchar **argv; - gint argc; - gint i; - - argv = g_application_command_line_get_arguments (cmdline, &argc); - - g_application_command_line_print (cmdline, - "This text is written back\n" - "to stdout of the caller\n"); - - for (i = 0; i < argc; i++) - g_print ("argument %d: %s\n", i, argv[i]); - - g_strfreev (argv); - - return 0; -} -]| -The complete example can be found here: -[gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) - -In more complicated cases, the handling of the comandline can be -split between the launcher and the primary instance. -|[<!-- language="C" --> -static gboolean - test_local_cmdline (GApplication *application, - gchar ***arguments, - gint *exit_status) -{ - gint i, j; - gchar **argv; - - argv = *arguments; - - i = 1; - while (argv[i]) - { - if (g_str_has_prefix (argv[i], "--local-")) - { - g_print ("handling argument %s locally\n", argv[i]); - g_free (argv[i]); - for (j = i; argv[j]; j++) - argv[j] = argv[j + 1]; - } - else - { - g_print ("not handling argument %s locally\n", argv[i]); - i++; - } - } - - *exit_status = 0; - - return FALSE; -} - -static void -test_application_class_init (TestApplicationClass *class) -{ - G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; - - ... -} -]| -In this example of split commandline handling, options that start -with `--local-` are handled locally, all other options are passed -to the #GApplication::command-line handler which runs in the primary -instance. - -The complete example can be found here: -[gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) - -If handling the commandline requires a lot of work, it may -be better to defer it. -|[<!-- language="C" --> -static gboolean -my_cmdline_handler (gpointer data) -{ - GApplicationCommandLine *cmdline = data; - - // do the heavy lifting in an idle - - g_application_command_line_set_exit_status (cmdline, 0); - g_object_unref (cmdline); // this releases the application - - return G_SOURCE_REMOVE; -} - -static int -command_line (GApplication *application, - GApplicationCommandLine *cmdline) -{ - // keep the application running until we are done with this commandline - g_application_hold (application); - - g_object_set_data_full (G_OBJECT (cmdline), - "application", application, - (GDestroyNotify)g_application_release); - - g_object_ref (cmdline); - g_idle_add (my_cmdline_handler, cmdline); - - return 0; -} -]| -In this example the commandline is not completely handled before -the #GApplication::command-line handler returns. Instead, we keep -a reference to the #GApplicationCommandLine object and handle it -later (in this example, in an idle). Note that it is necessary to -hold the application until you are done with the commandline. - -The complete example can be found here: -[gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) - - - Gets the stdin of the invoking process. - -The #GInputStream can be used to read data passed to the standard -input of the invoking process. -This doesn't work on all platforms. Presently, it is only available -on UNIX when using a DBus daemon capable of passing file descriptors. -If stdin is not available then %NULL will be returned. In the -future, support may be expanded to other platforms. - -You must only call this function once per commandline invocation. - - - a #GInputStream for stdin - - - - - a #GApplicationCommandLine - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a #GFile corresponding to a filename that was given as part -of the invocation of @cmdline. - -This differs from g_file_new_for_commandline_arg() in that it -resolves relative pathnames using the current working directory of -the invoking process rather than the local process. - - - a new #GFile - - - - - a #GApplicationCommandLine - - - - an argument from @cmdline - - - - - - Gets the list of arguments that was passed on the command line. - -The strings in the array may contain non-UTF-8 data on UNIX (such as -filenames or arguments given in the system locale) but are always in -UTF-8 on Windows. - -If you wish to use the return value with #GOptionContext, you must -use g_option_context_parse_strv(). - -The return value is %NULL-terminated and should be freed using -g_strfreev(). - - - - the string array containing the arguments (the argv) - - - - - - - a #GApplicationCommandLine - - - - the length of the arguments array, or %NULL - - - - - - Gets the working directory of the command line invocation. -The string may contain non-utf8 data. - -It is possible that the remote application did not send a working -directory, so this may be %NULL. - -The return value should not be modified or freed and is valid for as -long as @cmdline exists. - - - the current directory, or %NULL - - - - - a #GApplicationCommandLine - - - - - - Gets the contents of the 'environ' variable of the command line -invocation, as would be returned by g_get_environ(), ie as a -%NULL-terminated list of strings in the form 'NAME=VALUE'. -The strings may contain non-utf8 data. - -The remote application usually does not send an environment. Use -%G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag -set it is possible that the environment is still not available (due -to invocation messages from other applications). - -The return value should not be modified or freed and is valid for as -long as @cmdline exists. - -See g_application_command_line_getenv() if you are only interested -in the value of a single environment variable. - - - - the environment strings, or %NULL if they were not sent - - - - - - - a #GApplicationCommandLine - - - - - - Gets the exit status of @cmdline. See -g_application_command_line_set_exit_status() for more information. - - - the exit status - - - - - a #GApplicationCommandLine - - - - - - Determines if @cmdline represents a remote invocation. - - - %TRUE if the invocation was remote - - - - - a #GApplicationCommandLine - - - - - - Gets the options there were passed to g_application_command_line(). - -If you did not override local_command_line() then these are the same -options that were parsed according to the #GOptionEntrys added to the -application with g_application_add_main_option_entries() and possibly -modified from your GApplication::handle-local-options handler. - -If no options were sent then an empty dictionary is returned so that -you don't need to check for %NULL. - - - a #GVariantDict with the options - - - - - a #GApplicationCommandLine - - - - - - Gets the platform data associated with the invocation of @cmdline. - -This is a #GVariant dictionary containing information about the -context in which the invocation occurred. It typically contains -information like the current working directory and the startup -notification ID. - -For local invocation, it will be %NULL. - - - the platform data, or %NULL - - - - - #GApplicationCommandLine - - - - - - Gets the stdin of the invoking process. - -The #GInputStream can be used to read data passed to the standard -input of the invoking process. -This doesn't work on all platforms. Presently, it is only available -on UNIX when using a DBus daemon capable of passing file descriptors. -If stdin is not available then %NULL will be returned. In the -future, support may be expanded to other platforms. - -You must only call this function once per commandline invocation. - - - a #GInputStream for stdin - - - - - a #GApplicationCommandLine - - - - - - Gets the value of a particular environment variable of the command -line invocation, as would be returned by g_getenv(). The strings may -contain non-utf8 data. - -The remote application usually does not send an environment. Use -%G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag -set it is possible that the environment is still not available (due -to invocation messages from other applications). - -The return value should not be modified or freed and is valid for as -long as @cmdline exists. - - - the value of the variable, or %NULL if unset or unsent - - - - - a #GApplicationCommandLine - - - - the environment variable to get - - - - - - Formats a message and prints it using the stdout print handler in the -invoking process. - -If @cmdline is a local invocation then this is exactly equivalent to -g_print(). If @cmdline is remote then this is equivalent to calling -g_print() in the invoking process. - - - - - - - a #GApplicationCommandLine - - - - a printf-style format string - - - - arguments, as per @format - - - - - - Formats a message and prints it using the stderr print handler in the -invoking process. - -If @cmdline is a local invocation then this is exactly equivalent to -g_printerr(). If @cmdline is remote then this is equivalent to -calling g_printerr() in the invoking process. - - - - - - - a #GApplicationCommandLine - - - - a printf-style format string - - - - arguments, as per @format - - - - - - Sets the exit status that will be used when the invoking process -exits. - -The return value of the #GApplication::command-line signal is -passed to this function when the handler returns. This is the usual -way of setting the exit status. - -In the event that you want the remote invocation to continue running -and want to decide on the exit status in the future, you can use this -call. For the case of a remote invocation, the remote process will -typically exit when the last reference is dropped on @cmdline. The -exit status of the remote process will be equal to the last value -that was set with this function. - -In the case that the commandline invocation is local, the situation -is slightly more complicated. If the commandline invocation results -in the mainloop running (ie: because the use-count of the application -increased to a non-zero value) then the application is considered to -have been 'successful' in a certain sense, and the exit status is -always zero. If the application use count is zero, though, the exit -status of the local #GApplicationCommandLine is used. - - - - - - - a #GApplicationCommandLine - - - - the exit status - - - - - - - - - - - - - - - - - - - - - - - - - The #GApplicationCommandLineClass-struct -contains private data only. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GInputStream for stdin - - - - - a #GApplicationCommandLine - - - - - - - - - - - - - - - - Flags used to define the behaviour of a #GApplication. - - Default - - - Run as a service. In this mode, registration - fails if the service is already running, and the application - will initially wait up to 10 seconds for an initial activation - message to arrive. - - - Don't try to become the primary instance. - - - This application handles opening files (in - the primary instance). Note that this flag only affects the default - implementation of local_command_line(), and has no effect if - %G_APPLICATION_HANDLES_COMMAND_LINE is given. - See g_application_run() for details. - - - This application handles command line - arguments (in the primary instance). Note that this flag only affect - the default implementation of local_command_line(). - See g_application_run() for details. - - - Send the environment of the - launching process to the primary instance. Set this flag if your - application is expected to behave differently depending on certain - environment variables. For instance, an editor might be expected - to use the `GIT_COMMITTER_NAME` environment variable - when editing a git commit message. The environment is available - to the #GApplication::command-line signal handler, via - g_application_command_line_getenv(). - - - Make no attempts to do any of the typical - single-instance application negotiation, even if the application - ID is given. The application neither attempts to become the - owner of the application ID nor does it check if an existing - owner already exists. Everything occurs in the local process. - Since: 2.30. - - - Allow users to override the - application ID from the command line with `--gapplication-app-id`. - Since: 2.48 - - - Allow another instance to take over - the bus name. Since: 2.60 - - - Take over from another instance. This flag is - usually set by passing `--gapplication-replace` on the commandline. - Since: 2.60 - - - - - - - #GAskPasswordFlags are used to request specific information from the -user, or to notify the user of their choices in an authentication -situation. - - operation requires a password. - - - operation requires a username. - - - operation requires a domain. - - - operation supports saving settings. - - - operation supports anonymous users. - - - operation takes TCRYPT parameters (Since: 2.58) - - - - This is the asynchronous version of #GInitable; it behaves the same -in all ways except that initialization is asynchronous. For more details -see the descriptions on #GInitable. - -A class may implement both the #GInitable and #GAsyncInitable interfaces. - -Users of objects implementing this are not intended to use the interface -method directly; instead it will be used automatically in various ways. -For C applications you generally just call g_async_initable_new_async() -directly, or indirectly via a foo_thing_new_async() wrapper. This will call -g_async_initable_init_async() under the cover, calling back with %NULL and -a set %GError on failure. - -A typical implementation might look something like this: - -|[<!-- language="C" --> -enum { - NOT_INITIALIZED, - INITIALIZING, - INITIALIZED -}; - -static void -_foo_ready_cb (Foo *self) -{ - GList *l; - - self->priv->state = INITIALIZED; - - for (l = self->priv->init_results; l != NULL; l = l->next) - { - GTask *task = l->data; - - if (self->priv->success) - g_task_return_boolean (task, TRUE); - else - g_task_return_new_error (task, ...); - g_object_unref (task); - } - - g_list_free (self->priv->init_results); - self->priv->init_results = NULL; -} - -static void -foo_init_async (GAsyncInitable *initable, - int io_priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) -{ - Foo *self = FOO (initable); - GTask *task; - - task = g_task_new (initable, cancellable, callback, user_data); - - switch (self->priv->state) - { - case NOT_INITIALIZED: - _foo_get_ready (self); - self->priv->init_results = g_list_append (self->priv->init_results, - task); - self->priv->state = INITIALIZING; - break; - case INITIALIZING: - self->priv->init_results = g_list_append (self->priv->init_results, - task); - break; - case INITIALIZED: - if (!self->priv->success) - g_task_return_new_error (task, ...); - else - g_task_return_boolean (task, TRUE); - g_object_unref (task); - break; - } -} - -static gboolean -foo_init_finish (GAsyncInitable *initable, - GAsyncResult *result, - GError **error) -{ - g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); - - return g_task_propagate_boolean (G_TASK (result), error); -} - -static void -foo_async_initable_iface_init (gpointer g_iface, - gpointer data) -{ - GAsyncInitableIface *iface = g_iface; - - iface->init_async = foo_init_async; - iface->init_finish = foo_init_finish; -} -]| - - - Helper function for constructing #GAsyncInitable object. This is -similar to g_object_new() but also initializes the object asynchronously. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_new_finish() to get the new object and check -for any errors. - - - - - - - a #GType supporting #GAsyncInitable. - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the initialization is - finished - - - - the data to pass to callback function - - - - the name of the first property, or %NULL if no - properties - - - - the value of the first property, followed by other property - value pairs, and ended by %NULL. - - - - - - Helper function for constructing #GAsyncInitable object. This is -similar to g_object_new_valist() but also initializes the object -asynchronously. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_new_finish() to get the new object and check -for any errors. - - - - - - - a #GType supporting #GAsyncInitable. - - - - the name of the first property, followed by -the value, and other property value pairs, and ended by %NULL. - - - - The var args list generated from @first_property_name. - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the initialization is - finished - - - - the data to pass to callback function - - - - - - Helper function for constructing #GAsyncInitable object. This is -similar to g_object_newv() but also initializes the object asynchronously. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_new_finish() to get the new object and check -for any errors. - Use g_object_new_with_properties() and -g_async_initable_init_async() instead. See #GParameter for more information. - - - - - - - a #GType supporting #GAsyncInitable. - - - - the number of parameters in @parameters - - - - the parameters to use to construct the object - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the initialization is - finished - - - - the data to pass to callback function - - - - - - Starts asynchronous initialization of the object implementing the -interface. This must be done before any real use of the object after -initial construction. If the object also implements #GInitable you can -optionally call g_initable_init() instead. - -This method is intended for language bindings. If writing in C, -g_async_initable_new_async() should typically be used instead. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_init_finish() to get the result of the -initialization. - -Implementations may also support cancellation. If @cancellable is not -%NULL, then initialization can be cancelled by triggering the cancellable -object from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and -the object doesn't support cancellable initialization, the error -%G_IO_ERROR_NOT_SUPPORTED will be returned. - -As with #GInitable, if the object is not initialized, or initialization -returns with an error, then all operations on the object except -g_object_ref() and g_object_unref() are considered to be invalid, and -have undefined behaviour. They will often fail with g_critical() or -g_warning(), but this must not be relied on. - -Callers should not assume that a class which implements #GAsyncInitable can -be initialized multiple times; for more information, see g_initable_init(). -If a class explicitly supports being initialized multiple times, -implementation requires yielding all subsequent calls to init_async() on the -results of the first call. - -For classes that also support the #GInitable interface, the default -implementation of this method will run the g_initable_init() function -in a thread, so if you want to support asynchronous initialization via -threads, just implement the #GAsyncInitable interface without overriding -any interface methods. - - - - - - - a #GAsyncInitable. - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes asynchronous initialization and returns the result. -See g_async_initable_init_async(). - - - %TRUE if successful. If an error has occurred, this function -will return %FALSE and set @error appropriately if present. - - - - - a #GAsyncInitable. - - - - a #GAsyncResult. - - - - - - Starts asynchronous initialization of the object implementing the -interface. This must be done before any real use of the object after -initial construction. If the object also implements #GInitable you can -optionally call g_initable_init() instead. - -This method is intended for language bindings. If writing in C, -g_async_initable_new_async() should typically be used instead. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_init_finish() to get the result of the -initialization. - -Implementations may also support cancellation. If @cancellable is not -%NULL, then initialization can be cancelled by triggering the cancellable -object from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and -the object doesn't support cancellable initialization, the error -%G_IO_ERROR_NOT_SUPPORTED will be returned. - -As with #GInitable, if the object is not initialized, or initialization -returns with an error, then all operations on the object except -g_object_ref() and g_object_unref() are considered to be invalid, and -have undefined behaviour. They will often fail with g_critical() or -g_warning(), but this must not be relied on. - -Callers should not assume that a class which implements #GAsyncInitable can -be initialized multiple times; for more information, see g_initable_init(). -If a class explicitly supports being initialized multiple times, -implementation requires yielding all subsequent calls to init_async() on the -results of the first call. - -For classes that also support the #GInitable interface, the default -implementation of this method will run the g_initable_init() function -in a thread, so if you want to support asynchronous initialization via -threads, just implement the #GAsyncInitable interface without overriding -any interface methods. - - - - - - - a #GAsyncInitable. - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes asynchronous initialization and returns the result. -See g_async_initable_init_async(). - - - %TRUE if successful. If an error has occurred, this function -will return %FALSE and set @error appropriately if present. - - - - - a #GAsyncInitable. - - - - a #GAsyncResult. - - - - - - Finishes the async construction for the various g_async_initable_new -calls, returning the created object or %NULL on error. - - - a newly created #GObject, - or %NULL on error. Free with g_object_unref(). - - - - - the #GAsyncInitable from the callback - - - - the #GAsyncResult from the callback - - - - - - - Provides an interface for asynchronous initializing object such that -initialization may fail. - - - The parent interface. - - - - - - - - - - - a #GAsyncInitable. - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if successful. If an error has occurred, this function -will return %FALSE and set @error appropriately if present. - - - - - a #GAsyncInitable. - - - - a #GAsyncResult. - - - - - - - - Type definition for a function that will be called back when an asynchronous -operation within GIO has been completed. #GAsyncReadyCallback -callbacks from #GTask are guaranteed to be invoked in a later -iteration of the -[thread-default main context][g-main-context-push-thread-default] -where the #GTask was created. All other users of -#GAsyncReadyCallback must likewise call it asynchronously in a -later iteration of the main context. - - - - - - - the object the asynchronous operation was started with. - - - - a #GAsyncResult. - - - - user data passed to the callback. - - - - - - Provides a base class for implementing asynchronous function results. - -Asynchronous operations are broken up into two separate operations -which are chained together by a #GAsyncReadyCallback. To begin -an asynchronous operation, provide a #GAsyncReadyCallback to the -asynchronous function. This callback will be triggered when the -operation has completed, and must be run in a later iteration of -the [thread-default main context][g-main-context-push-thread-default] -from where the operation was initiated. It will be passed a -#GAsyncResult instance filled with the details of the operation's -success or failure, the object the asynchronous function was -started for and any error codes returned. The asynchronous callback -function is then expected to call the corresponding "_finish()" -function, passing the object the function was called for, the -#GAsyncResult instance, and (optionally) an @error to grab any -error conditions that may have occurred. - -The "_finish()" function for an operation takes the generic result -(of type #GAsyncResult) and returns the specific result that the -operation in question yields (e.g. a #GFileEnumerator for a -"enumerate children" operation). If the result or error status of the -operation is not needed, there is no need to call the "_finish()" -function; GIO will take care of cleaning up the result and error -information after the #GAsyncReadyCallback returns. You can pass -%NULL for the #GAsyncReadyCallback if you don't need to take any -action at all after the operation completes. Applications may also -take a reference to the #GAsyncResult and call "_finish()" later; -however, the "_finish()" function may be called at most once. - -Example of a typical asynchronous operation flow: -|[<!-- language="C" --> -void _theoretical_frobnitz_async (Theoretical *t, - GCancellable *c, - GAsyncReadyCallback cb, - gpointer u); - -gboolean _theoretical_frobnitz_finish (Theoretical *t, - GAsyncResult *res, - GError **e); - -static void -frobnitz_result_func (GObject *source_object, - GAsyncResult *res, - gpointer user_data) -{ - gboolean success = FALSE; - - success = _theoretical_frobnitz_finish (source_object, res, NULL); - - if (success) - g_printf ("Hurray!\n"); - else - g_printf ("Uh oh!\n"); - - ... - -} - -int main (int argc, void *argv[]) -{ - ... - - _theoretical_frobnitz_async (theoretical_data, - NULL, - frobnitz_result_func, - NULL); - - ... -} -]| - -The callback for an asynchronous operation is called only once, and is -always called, even in the case of a cancelled operation. On cancellation -the result is a %G_IO_ERROR_CANCELLED error. - -## I/O Priority # {#io-priority} - -Many I/O-related asynchronous operations have a priority parameter, -which is used in certain cases to determine the order in which -operations are executed. They are not used to determine system-wide -I/O scheduling. Priorities are integers, with lower numbers indicating -higher priority. It is recommended to choose priorities between -%G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT -as a default. - - - Gets the source object from a #GAsyncResult. - - - a new reference to the source - object for the @res, or %NULL if there is none. - - - - - a #GAsyncResult - - - - - - Gets the user data from a #GAsyncResult. - - - the user data for @res. - - - - - a #GAsyncResult. - - - - - - Checks if @res has the given @source_tag (generally a function -pointer indicating the function @res was created by). - - - %TRUE if @res has the indicated @source_tag, %FALSE if - not. - - - - - a #GAsyncResult - - - - an application-defined tag - - - - - - Gets the source object from a #GAsyncResult. - - - a new reference to the source - object for the @res, or %NULL if there is none. - - - - - a #GAsyncResult - - - - - - Gets the user data from a #GAsyncResult. - - - the user data for @res. - - - - - a #GAsyncResult. - - - - - - Checks if @res has the given @source_tag (generally a function -pointer indicating the function @res was created by). - - - %TRUE if @res has the indicated @source_tag, %FALSE if - not. - - - - - a #GAsyncResult - - - - an application-defined tag - - - - - - If @res is a #GSimpleAsyncResult, this is equivalent to -g_simple_async_result_propagate_error(). Otherwise it returns -%FALSE. - -This can be used for legacy error handling in async *_finish() -wrapper functions that traditionally handled #GSimpleAsyncResult -error returns themselves rather than calling into the virtual method. -This should not be used in new code; #GAsyncResult errors that are -set by virtual methods should also be extracted by virtual methods, -to enable subclasses to chain up correctly. - - - %TRUE if @error is has been filled in with an error from - @res, %FALSE if not. - - - - - a #GAsyncResult - - - - - - - Interface definition for #GAsyncResult. - - - The parent interface. - - - - - - - the user data for @res. - - - - - a #GAsyncResult. - - - - - - - - - - a new reference to the source - object for the @res, or %NULL if there is none. - - - - - a #GAsyncResult - - - - - - - - - - %TRUE if @res has the indicated @source_tag, %FALSE if - not. - - - - - a #GAsyncResult - - - - an application-defined tag - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Buffered input stream implements #GFilterInputStream and provides -for buffered reads. - -By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. - -To create a buffered input stream, use g_buffered_input_stream_new(), -or g_buffered_input_stream_new_sized() to specify the buffer's size at -construction. - -To get the size of a buffer within a buffered input stream, use -g_buffered_input_stream_get_buffer_size(). To change the size of a -buffered input stream's buffer, use -g_buffered_input_stream_set_buffer_size(). Note that the buffer's size -cannot be reduced below the size of the data within the buffer. - - - - Creates a new #GInputStream from the given @base_stream, with -a buffer set to the default size (4 kilobytes). - - - a #GInputStream for the given @base_stream. - - - - - a #GInputStream - - - - - - Creates a new #GBufferedInputStream from the given @base_stream, -with a buffer set to @size. - - - a #GInputStream. - - - - - a #GInputStream - - - - a #gsize - - - - - - Tries to read @count bytes from the stream into the buffer. -Will block during this read. - -If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes read into the buffer is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -If @count is -1 then the attempted read size is equal to the number of -bytes that are required to fill the buffer. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - -For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). - - - the number of bytes read into @stream's buffer, up to @count, - or -1 on error. - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - optional #GCancellable object, %NULL to ignore - - - - - - Reads data into @stream's buffer asynchronously, up to @count size. -@io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). - -If @count is -1 then the attempted read size is equal to the number -of bytes that are required to fill the buffer. - - - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - Finishes an asynchronous read. - - - a #gssize of the read stream, or `-1` on an error. - - - - - a #GBufferedInputStream - - - - a #GAsyncResult - - - - - - Tries to read @count bytes from the stream into the buffer. -Will block during this read. - -If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes read into the buffer is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -If @count is -1 then the attempted read size is equal to the number of -bytes that are required to fill the buffer. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - -For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). - - - the number of bytes read into @stream's buffer, up to @count, - or -1 on error. - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - optional #GCancellable object, %NULL to ignore - - - - - - Reads data into @stream's buffer asynchronously, up to @count size. -@io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). - -If @count is -1 then the attempted read size is equal to the number -of bytes that are required to fill the buffer. - - - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - Finishes an asynchronous read. - - - a #gssize of the read stream, or `-1` on an error. - - - - - a #GBufferedInputStream - - - - a #GAsyncResult - - - - - - Gets the size of the available data within the stream. - - - size of the available stream. - - - - - #GBufferedInputStream - - - - - - Gets the size of the input buffer. - - - the current buffer size. - - - - - a #GBufferedInputStream - - - - - - Peeks in the buffer, copying data of size @count into @buffer, -offset @offset bytes. - - - a #gsize of the number of bytes peeked, or -1 on error. - - - - - a #GBufferedInputStream - - - - a pointer to - an allocated chunk of memory - - - - - - a #gsize - - - - a #gsize - - - - - - Returns the buffer with the currently available bytes. The returned -buffer must not be modified and will become invalid when reading from -the stream or filling the buffer. - - - - read-only buffer - - - - - - - a #GBufferedInputStream - - - - a #gsize to get the number of bytes available in the buffer - - - - - - Tries to read a single byte from the stream or the buffer. Will block -during this read. - -On success, the byte read from the stream is returned. On end of stream --1 is returned but it's not an exceptional error and @error is not set. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - - - the byte read from the @stream, or -1 on end of stream or error. - - - - - a #GBufferedInputStream - - - - optional #GCancellable object, %NULL to ignore - - - - - - Sets the size of the internal buffer of @stream to @size, or to the -size of the contents of the buffer. The buffer can never be resized -smaller than its current contents. - - - - - - - a #GBufferedInputStream - - - - a #gsize - - - - - - - - - - - - - - - - - - - - - - - - the number of bytes read into @stream's buffer, up to @count, - or -1 on error. - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - optional #GCancellable object, %NULL to ignore - - - - - - - - - - - - - - a #GBufferedInputStream - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - - - - - a #gssize of the read stream, or `-1` on an error. - - - - - a #GBufferedInputStream - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Buffered output stream implements #GFilterOutputStream and provides -for buffered writes. - -By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. - -To create a buffered output stream, use g_buffered_output_stream_new(), -or g_buffered_output_stream_new_sized() to specify the buffer's size -at construction. - -To get the size of a buffer within a buffered input stream, use -g_buffered_output_stream_get_buffer_size(). To change the size of a -buffered output stream's buffer, use -g_buffered_output_stream_set_buffer_size(). Note that the buffer's -size cannot be reduced below the size of the data within the buffer. - - - - Creates a new buffered output stream for a base stream. - - - a #GOutputStream for the given @base_stream. - - - - - a #GOutputStream. - - - - - - Creates a new buffered output stream with a given buffer size. - - - a #GOutputStream with an internal buffer set to @size. - - - - - a #GOutputStream. - - - - a #gsize. - - - - - - Checks if the buffer automatically grows as data is added. - - - %TRUE if the @stream's buffer automatically grows, -%FALSE otherwise. - - - - - a #GBufferedOutputStream. - - - - - - Gets the size of the buffer in the @stream. - - - the current size of the buffer. - - - - - a #GBufferedOutputStream. - - - - - - Sets whether or not the @stream's buffer should automatically grow. -If @auto_grow is true, then each write will just make the buffer -larger, and you must manually flush the buffer to actually write out -the data to the underlying stream. - - - - - - - a #GBufferedOutputStream. - - - - a #gboolean. - - - - - - Sets the size of the internal buffer to @size. - - - - - - - a #GBufferedOutputStream. - - - - a #gsize. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Invoked when a connection to a message bus has been obtained. - - - - - - - The #GDBusConnection to a message bus. - - - - The name that is requested to be owned. - - - - User data passed to g_bus_own_name(). - - - - - - Invoked when the name is acquired. - - - - - - - The #GDBusConnection on which to acquired the name. - - - - The name being owned. - - - - User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). - - - - - - Invoked when the name being watched is known to have to have an owner. - - - - - - - The #GDBusConnection the name is being watched on. - - - - The name being watched. - - - - Unique name of the owner of the name being watched. - - - - User data passed to g_bus_watch_name(). - - - - - - Invoked when the name is lost or @connection has been closed. - - - - - - - The #GDBusConnection on which to acquire the name or %NULL if -the connection was disconnected. - - - - The name being owned. - - - - User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). - - - - - - Flags used in g_bus_own_name(). - - No flags set. - - - Allow another message bus connection to claim the name. - - - If another message bus connection owns the name and have -specified #G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. - - - If another message bus connection owns the name, immediately -return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54) - - - - Invoked when the name being watched is known not to have to have an owner. - -This is also invoked when the #GDBusConnection on which the watch was -established has been closed. In that case, @connection will be -%NULL. - - - - - - - The #GDBusConnection the name is being watched on, or - %NULL. - - - - The name being watched. - - - - User data passed to g_bus_watch_name(). - - - - - - Flags used in g_bus_watch_name(). - - No flags set. - - - If no-one owns the name when -beginning to watch the name, ask the bus to launch an owner for the -name. - - - - An enumeration for well-known message buses. - - An alias for the message bus that activated the process, if any. - - - Not a message bus. - - - The system-wide message bus. - - - The login session message bus. - - - - #GBytesIcon specifies an image held in memory in a common format (usually -png) to be used as icon. - - - - Creates a new icon for a bytes. - - - a #GIcon for the given - @bytes, or %NULL on error. - - - - - a #GBytes. - - - - - - Gets the #GBytes associated with the given @icon. - - - a #GBytes, or %NULL. - - - - - a #GIcon. - - - - - - The bytes containing the icon. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GCancellable is a thread-safe operation cancellation stack used -throughout GIO to allow for cancellation of synchronous and -asynchronous operations. - - - Creates a new #GCancellable object. - -Applications that want to start one or more operations -that should be cancellable should create a #GCancellable -and pass it to the operations. - -One #GCancellable can be used in multiple consecutive -operations or in multiple concurrent operations. - - - a #GCancellable. - - - - - Gets the top cancellable from the stack. - - - a #GCancellable from the top -of the stack, or %NULL if the stack is empty. - - - - - - - - - - - - - - - - Will set @cancellable to cancelled, and will emit the -#GCancellable::cancelled signal. (However, see the warning about -race conditions in the documentation for that signal if you are -planning to connect to it.) - -This function is thread-safe. In other words, you can safely call -it from a thread other than the one running the operation that was -passed the @cancellable. - -If @cancellable is %NULL, this function returns immediately for convenience. - -The convention within GIO is that cancelling an asynchronous -operation causes it to complete asynchronously. That is, if you -cancel the operation from the same thread in which it is running, -then the operation's #GAsyncReadyCallback will not be invoked until -the application returns to the main loop. - - - - - - - a #GCancellable object. - - - - - - Convenience function to connect to the #GCancellable::cancelled -signal. Also handles the race condition that may happen -if the cancellable is cancelled right before connecting. - -@callback is called at most once, either directly at the -time of the connect if @cancellable is already cancelled, -or when @cancellable is cancelled in some thread. - -@data_destroy_func will be called when the handler is -disconnected, or immediately if the cancellable is already -cancelled. - -See #GCancellable::cancelled for details on how to use this. - -Since GLib 2.40, the lock protecting @cancellable is not held when -@callback is invoked. This lifts a restriction in place for -earlier GLib versions which now makes it easier to write cleanup -code that unconditionally invokes e.g. g_cancellable_cancel(). - - - The id of the signal handler or 0 if @cancellable has already - been cancelled. - - - - - A #GCancellable. - - - - The #GCallback to connect. - - - - Data to pass to @callback. - - - - Free function for @data or %NULL. - - - - - - Disconnects a handler from a cancellable instance similar to -g_signal_handler_disconnect(). Additionally, in the event that a -signal handler is currently running, this call will block until the -handler has finished. Calling this function from a -#GCancellable::cancelled signal handler will therefore result in a -deadlock. - -This avoids a race condition where a thread cancels at the -same time as the cancellable operation is finished and the -signal handler is removed. See #GCancellable::cancelled for -details on how to use this. - -If @cancellable is %NULL or @handler_id is `0` this function does -nothing. - - - - - - - A #GCancellable or %NULL. - - - - Handler id of the handler to be disconnected, or `0`. - - - - - - Gets the file descriptor for a cancellable job. This can be used to -implement cancellable operations on Unix systems. The returned fd will -turn readable when @cancellable is cancelled. - -You are not supposed to read from the fd yourself, just check for -readable status. Reading to unset the readable status is done -with g_cancellable_reset(). - -After a successful return from this function, you should use -g_cancellable_release_fd() to free up resources allocated for -the returned file descriptor. - -See also g_cancellable_make_pollfd(). - - - A valid file descriptor. `-1` if the file descriptor -is not supported, or on errors. - - - - - a #GCancellable. - - - - - - Checks if a cancellable job has been cancelled. - - - %TRUE if @cancellable is cancelled, -FALSE if called with %NULL or if item is not cancelled. - - - - - a #GCancellable or %NULL - - - - - - Creates a #GPollFD corresponding to @cancellable; this can be passed -to g_poll() and used to poll for cancellation. This is useful both -for unix systems without a native poll and for portability to -windows. - -When this function returns %TRUE, you should use -g_cancellable_release_fd() to free up resources allocated for the -@pollfd. After a %FALSE return, do not call g_cancellable_release_fd(). - -If this function returns %FALSE, either no @cancellable was given or -resource limits prevent this function from allocating the necessary -structures for polling. (On Linux, you will likely have reached -the maximum number of file descriptors.) The suggested way to handle -these cases is to ignore the @cancellable. - -You are not supposed to read from the fd yourself, just check for -readable status. Reading to unset the readable status is done -with g_cancellable_reset(). - - - %TRUE if @pollfd was successfully initialized, %FALSE on - failure to prepare the cancellable. - - - - - a #GCancellable or %NULL - - - - a pointer to a #GPollFD - - - - - - Pops @cancellable off the cancellable stack (verifying that @cancellable -is on the top of the stack). - - - - - - - a #GCancellable object - - - - - - Pushes @cancellable onto the cancellable stack. The current -cancellable can then be received using g_cancellable_get_current(). - -This is useful when implementing cancellable operations in -code that does not allow you to pass down the cancellable object. - -This is typically called automatically by e.g. #GFile operations, -so you rarely have to call this yourself. - - - - - - - a #GCancellable object - - - - - - Releases a resources previously allocated by g_cancellable_get_fd() -or g_cancellable_make_pollfd(). - -For compatibility reasons with older releases, calling this function -is not strictly required, the resources will be automatically freed -when the @cancellable is finalized. However, the @cancellable will -block scarce file descriptors until it is finalized if this function -is not called. This can cause the application to run out of file -descriptors when many #GCancellables are used at the same time. - - - - - - - a #GCancellable - - - - - - Resets @cancellable to its uncancelled state. - -If cancellable is currently in use by any cancellable operation -then the behavior of this function is undefined. - -Note that it is generally not a good idea to reuse an existing -cancellable for more operations after it has been cancelled once, -as this function might tempt you to do. The recommended practice -is to drop the reference to a cancellable after cancelling it, -and let it die with the outstanding async operations. You should -create a fresh cancellable for further async operations. - - - - - - - a #GCancellable object. - - - - - - If the @cancellable is cancelled, sets the error to notify -that the operation was cancelled. - - - %TRUE if @cancellable was cancelled, %FALSE if it was not - - - - - a #GCancellable or %NULL - - - - - - Creates a source that triggers if @cancellable is cancelled and -calls its callback of type #GCancellableSourceFunc. This is -primarily useful for attaching to another (non-cancellable) source -with g_source_add_child_source() to add cancellability to it. - -For convenience, you can call this with a %NULL #GCancellable, -in which case the source will never trigger. - -The new #GSource will hold a reference to the #GCancellable. - - - the new #GSource. - - - - - a #GCancellable, or %NULL - - - - - - - - - - - - Emitted when the operation has been cancelled. - -Can be used by implementations of cancellable operations. If the -operation is cancelled from another thread, the signal will be -emitted in the thread that cancelled the operation, not the -thread that is running the operation. - -Note that disconnecting from this signal (or any signal) in a -multi-threaded program is prone to race conditions. For instance -it is possible that a signal handler may be invoked even after -a call to g_signal_handler_disconnect() for that handler has -already returned. - -There is also a problem when cancellation happens right before -connecting to the signal. If this happens the signal will -unexpectedly not be emitted, and checking before connecting to -the signal leaves a race condition where this is still happening. - -In order to make it safe and easy to connect handlers there -are two helper functions: g_cancellable_connect() and -g_cancellable_disconnect() which protect against problems -like this. - -An example of how to us this: -|[<!-- language="C" --> - // Make sure we don't do unnecessary work if already cancelled - if (g_cancellable_set_error_if_cancelled (cancellable, error)) - return; - - // Set up all the data needed to be able to handle cancellation - // of the operation - my_data = my_data_new (...); - - id = 0; - if (cancellable) - id = g_cancellable_connect (cancellable, - G_CALLBACK (cancelled_handler) - data, NULL); - - // cancellable operation here... - - g_cancellable_disconnect (cancellable, id); - - // cancelled_handler is never called after this, it is now safe - // to free the data - my_data_free (my_data); -]| - -Note that the cancelled signal is emitted in the thread that -the user cancelled from, which may be the main thread. So, the -cancellable signal should not do something that can block. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This is the function type of the callback used for the #GSource -returned by g_cancellable_source_new(). - - - it should return %FALSE if the source should be removed. - - - - - the #GCancellable - - - - data passed in by the user. - - - - - - #GCharsetConverter is an implementation of #GConverter based on -GIConv. - - - - - Creates a new #GCharsetConverter. - - - a new #GCharsetConverter or %NULL on error. - - - - - destination charset - - - - source charset - - - - - - Gets the number of fallbacks that @converter has applied so far. - - - the number of fallbacks that @converter has applied - - - - - a #GCharsetConverter - - - - - - Gets the #GCharsetConverter:use-fallback property. - - - %TRUE if fallbacks are used by @converter - - - - - a #GCharsetConverter - - - - - - Sets the #GCharsetConverter:use-fallback property. - - - - - - - a #GCharsetConverter - - - - %TRUE to use fallbacks - - - - - - - - - - - - - - - - - - - - - - #GConverter is implemented by objects that convert -binary data in various ways. The conversion can be -stateful and may fail at any place. - -Some example conversions are: character set conversion, -compression, decompression and regular expression -replace. - - - This is the main operation used when converting data. It is to be called -multiple times in a loop, and each time it will do some work, i.e. -producing some output (in @outbuf) or consuming some input (from @inbuf) or -both. If its not possible to do any work an error is returned. - -Note that a single call may not consume all input (or any input at all). -Also a call may produce output even if given no input, due to state stored -in the converter producing output. - -If any data was either produced or consumed, and then an error happens, then -only the successful conversion is reported and the error is returned on the -next call. - -A full conversion loop involves calling this method repeatedly, each time -giving it new input and space output space. When there is no more input -data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. -The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED -each time until all data is consumed and all output is produced, then -%G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED -may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance -in a decompression converter where the end of data is detectable from the -data (and there might even be other data after the end of the compressed data). - -When some data has successfully been converted @bytes_read and is set to -the number of bytes read from @inbuf, and @bytes_written is set to indicate -how many bytes was written to @outbuf. If there are more data to output -or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then -%G_CONVERTER_CONVERTED is returned, and if no more data is to be output -then %G_CONVERTER_FINISHED is returned. - -On error %G_CONVERTER_ERROR is returned and @error is set accordingly. -Some errors need special handling: - -%G_IO_ERROR_NO_SPACE is returned if there is not enough space -to write the resulting converted data, the application should -call the function again with a larger @outbuf to continue. - -%G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough -input to fully determine what the conversion should produce, -and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for -example with an incomplete multibyte sequence when converting text, -or when a regexp matches up to the end of the input (and may match -further input). It may also happen when @inbuf_size is zero and -there is no more data to produce. - -When this happens the application should read more input and then -call the function again. If further input shows that there is no -more data call the function again with the same data but with -the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion -to finish as e.g. in the regexp match case (or, to fail again with -%G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the -input is actually partial). - -After g_converter_convert() has returned %G_CONVERTER_FINISHED the -converter object is in an invalid state where its not allowed -to call g_converter_convert() anymore. At this time you can only -free the object or call g_converter_reset() to reset it to the -initial state. - -If the flag %G_CONVERTER_FLUSH is set then conversion is modified -to try to write out all internal state to the output. The application -has to call the function multiple times with the flag set, and when -the available input has been consumed and all internal state has -been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if -really at the end) is returned instead of %G_CONVERTER_CONVERTED. -This is somewhat similar to what happens at the end of the input stream, -but done in the middle of the data. - -This has different meanings for different conversions. For instance -in a compression converter it would mean that we flush all the -compression state into output such that if you uncompress the -compressed data you get back all the input data. Doing this may -make the final file larger due to padding though. Another example -is a regexp conversion, where if you at the end of the flushed data -have a match, but there is also a potential longer match. In the -non-flushed case we would ask for more input, but when flushing we -treat this as the end of input and do the match. - -Flushing is not always possible (like if a charset converter flushes -at a partial multibyte sequence). Converters are supposed to try -to produce as much output as possible and then return an error -(typically %G_IO_ERROR_PARTIAL_INPUT). - - - a #GConverterResult, %G_CONVERTER_ERROR on error. - - - - - a #GConverter. - - - - the buffer - containing the data to convert. - - - - - - the number of bytes in @inbuf - - - - a buffer to write - converted data in. - - - - - - the number of bytes in @outbuf, must be at least one - - - - a #GConverterFlags controlling the conversion details - - - - will be set to the number of bytes read from @inbuf on success - - - - will be set to the number of bytes written to @outbuf on success - - - - - - Resets all internal state in the converter, making it behave -as if it was just created. If the converter has any internal -state that would produce output then that output is lost. - - - - - - - a #GConverter. - - - - - - This is the main operation used when converting data. It is to be called -multiple times in a loop, and each time it will do some work, i.e. -producing some output (in @outbuf) or consuming some input (from @inbuf) or -both. If its not possible to do any work an error is returned. - -Note that a single call may not consume all input (or any input at all). -Also a call may produce output even if given no input, due to state stored -in the converter producing output. - -If any data was either produced or consumed, and then an error happens, then -only the successful conversion is reported and the error is returned on the -next call. - -A full conversion loop involves calling this method repeatedly, each time -giving it new input and space output space. When there is no more input -data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. -The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED -each time until all data is consumed and all output is produced, then -%G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED -may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance -in a decompression converter where the end of data is detectable from the -data (and there might even be other data after the end of the compressed data). - -When some data has successfully been converted @bytes_read and is set to -the number of bytes read from @inbuf, and @bytes_written is set to indicate -how many bytes was written to @outbuf. If there are more data to output -or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then -%G_CONVERTER_CONVERTED is returned, and if no more data is to be output -then %G_CONVERTER_FINISHED is returned. - -On error %G_CONVERTER_ERROR is returned and @error is set accordingly. -Some errors need special handling: - -%G_IO_ERROR_NO_SPACE is returned if there is not enough space -to write the resulting converted data, the application should -call the function again with a larger @outbuf to continue. - -%G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough -input to fully determine what the conversion should produce, -and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for -example with an incomplete multibyte sequence when converting text, -or when a regexp matches up to the end of the input (and may match -further input). It may also happen when @inbuf_size is zero and -there is no more data to produce. - -When this happens the application should read more input and then -call the function again. If further input shows that there is no -more data call the function again with the same data but with -the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion -to finish as e.g. in the regexp match case (or, to fail again with -%G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the -input is actually partial). - -After g_converter_convert() has returned %G_CONVERTER_FINISHED the -converter object is in an invalid state where its not allowed -to call g_converter_convert() anymore. At this time you can only -free the object or call g_converter_reset() to reset it to the -initial state. - -If the flag %G_CONVERTER_FLUSH is set then conversion is modified -to try to write out all internal state to the output. The application -has to call the function multiple times with the flag set, and when -the available input has been consumed and all internal state has -been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if -really at the end) is returned instead of %G_CONVERTER_CONVERTED. -This is somewhat similar to what happens at the end of the input stream, -but done in the middle of the data. - -This has different meanings for different conversions. For instance -in a compression converter it would mean that we flush all the -compression state into output such that if you uncompress the -compressed data you get back all the input data. Doing this may -make the final file larger due to padding though. Another example -is a regexp conversion, where if you at the end of the flushed data -have a match, but there is also a potential longer match. In the -non-flushed case we would ask for more input, but when flushing we -treat this as the end of input and do the match. - -Flushing is not always possible (like if a charset converter flushes -at a partial multibyte sequence). Converters are supposed to try -to produce as much output as possible and then return an error -(typically %G_IO_ERROR_PARTIAL_INPUT). - - - a #GConverterResult, %G_CONVERTER_ERROR on error. - - - - - a #GConverter. - - - - the buffer - containing the data to convert. - - - - - - the number of bytes in @inbuf - - - - a buffer to write - converted data in. - - - - - - the number of bytes in @outbuf, must be at least one - - - - a #GConverterFlags controlling the conversion details - - - - will be set to the number of bytes read from @inbuf on success - - - - will be set to the number of bytes written to @outbuf on success - - - - - - Resets all internal state in the converter, making it behave -as if it was just created. If the converter has any internal -state that would produce output then that output is lost. - - - - - - - a #GConverter. - - - - - - - Flags used when calling a g_converter_convert(). - - No flags. - - - At end of input data - - - Flush data - - - - Provides an interface for converting data from one type -to another type. The conversion can be stateful -and may fail at any place. - - - The parent interface. - - - - - - - a #GConverterResult, %G_CONVERTER_ERROR on error. - - - - - a #GConverter. - - - - the buffer - containing the data to convert. - - - - - - the number of bytes in @inbuf - - - - a buffer to write - converted data in. - - - - - - the number of bytes in @outbuf, must be at least one - - - - a #GConverterFlags controlling the conversion details - - - - will be set to the number of bytes read from @inbuf on success - - - - will be set to the number of bytes written to @outbuf on success - - - - - - - - - - - - - - a #GConverter. - - - - - - - - Converter input stream implements #GInputStream and allows -conversion of data of various types during reading. - -As of GLib 2.34, #GConverterInputStream implements -#GPollableInputStream. - - - - Creates a new converter input stream for the @base_stream. - - - a new #GInputStream. - - - - - a #GInputStream - - - - a #GConverter - - - - - - Gets the #GConverter that is used by @converter_stream. - - - the converter of the converter input stream - - - - - a #GConverterInputStream - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Converter output stream implements #GOutputStream and allows -conversion of data of various types during reading. - -As of GLib 2.34, #GConverterOutputStream implements -#GPollableOutputStream. - - - - Creates a new converter output stream for the @base_stream. - - - a new #GOutputStream. - - - - - a #GOutputStream - - - - a #GConverter - - - - - - Gets the #GConverter that is used by @converter_stream. - - - the converter of the converter output stream - - - - - a #GConverterOutputStream - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Results returned from g_converter_convert(). - - There was an error during conversion. - - - Some data was consumed or produced - - - The conversion is finished - - - Flushing is finished - - - - The #GCredentials type is a reference-counted wrapper for native -credentials. This information is typically used for identifying, -authenticating and authorizing other processes. - -Some operating systems supports looking up the credentials of the -remote peer of a communication endpoint - see e.g. -g_socket_get_credentials(). - -Some operating systems supports securely sending and receiving -credentials over a Unix Domain Socket, see -#GUnixCredentialsMessage, g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials() for details. - -On Linux, the native credential type is a struct ucred - see the -unix(7) man page for details. This corresponds to -%G_CREDENTIALS_TYPE_LINUX_UCRED. - -On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native -credential type is a struct cmsgcred. This corresponds -to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. - -On NetBSD, the native credential type is a struct unpcbid. -This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. - -On OpenBSD, the native credential type is a struct sockpeercred. -This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. - -On Solaris (including OpenSolaris and its derivatives), the native -credential type is a ucred_t. This corresponds to -%G_CREDENTIALS_TYPE_SOLARIS_UCRED. - - - Creates a new #GCredentials object with credentials matching the -the current process. - - - A #GCredentials. Free with g_object_unref(). - - - - - Gets a pointer to native credentials of type @native_type from -@credentials. - -It is a programming error (which will cause a warning to be -logged) to use this method if there is no #GCredentials support for -the OS or if @native_type isn't supported by the OS. - - - The pointer to native credentials or %NULL if the -operation there is no #GCredentials support for the OS or if -@native_type isn't supported by the OS. Do not free the returned -data, it is owned by @credentials. - - - - - A #GCredentials. - - - - The type of native credentials to get. - - - - - - Tries to get the UNIX process identifier from @credentials. This -method is only available on UNIX platforms. - -This operation can fail if #GCredentials is not supported on the -OS or if the native credentials type does not contain information -about the UNIX process ID. - - - The UNIX process ID, or -1 if @error is set. - - - - - A #GCredentials - - - - - - Tries to get the UNIX user identifier from @credentials. This -method is only available on UNIX platforms. - -This operation can fail if #GCredentials is not supported on the -OS or if the native credentials type does not contain information -about the UNIX user. - - - The UNIX user identifier or -1 if @error is set. - - - - - A #GCredentials - - - - - - Checks if @credentials and @other_credentials is the same user. - -This operation can fail if #GCredentials is not supported on the -the OS. - - - %TRUE if @credentials and @other_credentials has the same -user, %FALSE otherwise or if @error is set. - - - - - A #GCredentials. - - - - A #GCredentials. - - - - - - Copies the native credentials of type @native_type from @native -into @credentials. - -It is a programming error (which will cause a warning to be -logged) to use this method if there is no #GCredentials support for -the OS or if @native_type isn't supported by the OS. - - - - - - - A #GCredentials. - - - - The type of native credentials to set. - - - - A pointer to native credentials. - - - - - - Tries to set the UNIX user identifier on @credentials. This method -is only available on UNIX platforms. - -This operation can fail if #GCredentials is not supported on the -OS or if the native credentials type does not contain information -about the UNIX user. It can also fail if the OS does not allow the -use of "spoofed" credentials. - - - %TRUE if @uid was set, %FALSE if error is set. - - - - - A #GCredentials. - - - - The UNIX user identifier to set. - - - - - - Creates a human-readable textual representation of @credentials -that can be used in logging and debug messages. The format of the -returned string may change in future GLib release. - - - A string that should be freed with g_free(). - - - - - A #GCredentials object. - - - - - - - Class structure for #GCredentials. - - - - Enumeration describing different kinds of native credential types. - - Indicates an invalid native credential type. - - - The native credentials type is a struct ucred. - - - The native credentials type is a struct cmsgcred. - - - The native credentials type is a struct sockpeercred. Added in 2.30. - - - The native credentials type is a ucred_t. Added in 2.40. - - - The native credentials type is a struct unpcbid. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GDBusActionGroup is an implementation of the #GActionGroup -interface that can be used as a proxy for an action group -that is exported over D-Bus with g_dbus_connection_export_action_group(). - - - - Obtains a #GDBusActionGroup for the action group which is exported at -the given @bus_name and @object_path. - -The thread default main context is taken at the time of this call. -All signals on the menu model (and any linked models) are reported -with respect to this context. All calls on the returned menu model -(and linked models) must also originate from this same context, with -the thread default main context unchanged. - -This call is non-blocking. The returned action group may or may not -already be filled in. The correct thing to do is connect the signals -for the action group to monitor for changes and then to call -g_action_group_list_actions() to get the initial list. - - - a #GDBusActionGroup - - - - - A #GDBusConnection - - - - the bus name which exports the action - group or %NULL if @connection is not a message bus connection - - - - the object path at which the action group is exported - - - - - - - Information about an annotation. - - - The reference count or -1 if statically allocated. - - - - The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". - - - - The value of the annotation. - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusNodeInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusAnnotationInfo. - - - - - - Looks up the value of an annotation. - -The cost of this function is O(n) in number of annotations. - - - The value or %NULL if not found. Do not free, it is owned by @annotations. - - - - - A %NULL-terminated array of annotations or %NULL. - - - - - - The name of the annotation to look up. - - - - - - - Information about an argument for a method or a signal. - - - The reference count or -1 if statically allocated. - - - - Name of the argument, e.g. @unix_user_id. - - - - D-Bus signature of the argument (a single complete type). - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusArgInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusArgInfo. - - - - - - - The #GDBusAuthObserver type provides a mechanism for participating -in how a #GDBusServer (or a #GDBusConnection) authenticates remote -peers. Simply instantiate a #GDBusAuthObserver and connect to the -signals you are interested in. Note that new signals may be added -in the future - -## Controlling Authentication Mechanisms - -By default, a #GDBusServer or server-side #GDBusConnection will allow -any authentication mechanism to be used. If you only -want to allow D-Bus connections with the `EXTERNAL` mechanism, -which makes use of credentials passing and is the recommended -mechanism for modern Unix platforms such as Linux and the BSD family, -you would use a signal handler like this: - -|[<!-- language="C" --> -static gboolean -on_allow_mechanism (GDBusAuthObserver *observer, - const gchar *mechanism, - gpointer user_data) -{ - if (g_strcmp0 (mechanism, "EXTERNAL") == 0) - { - return TRUE; - } - - return FALSE; -} -]| - -## Controlling Authorization # {#auth-observer} - -By default, a #GDBusServer or server-side #GDBusConnection will accept -connections from any successfully authenticated user (but not from -anonymous connections using the `ANONYMOUS` mechanism). If you only -want to allow D-Bus connections from processes owned by the same uid -as the server, you would use a signal handler like the following: - -|[<!-- language="C" --> -static gboolean -on_authorize_authenticated_peer (GDBusAuthObserver *observer, - GIOStream *stream, - GCredentials *credentials, - gpointer user_data) -{ - gboolean authorized; - - authorized = FALSE; - if (credentials != NULL) - { - GCredentials *own_credentials; - own_credentials = g_credentials_new (); - if (g_credentials_is_same_user (credentials, own_credentials, NULL)) - authorized = TRUE; - g_object_unref (own_credentials); - } - - return authorized; -} -]| - - Creates a new #GDBusAuthObserver object. - - - A #GDBusAuthObserver. Free with g_object_unref(). - - - - - Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. - - - %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. - - - - - A #GDBusAuthObserver. - - - - The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. - - - - - - Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. - - - %TRUE if the peer is authorized, %FALSE if not. - - - - - A #GDBusAuthObserver. - - - - A #GIOStream for the #GDBusConnection. - - - - Credentials received from the peer or %NULL. - - - - - - Emitted to check if @mechanism is allowed to be used. - - %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. - - - - - The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. - - - - - - Emitted to check if a peer that is successfully authenticated -is authorized. - - %TRUE if the peer is authorized, %FALSE if not. - - - - - A #GIOStream for the #GDBusConnection. - - - - Credentials received from the peer or %NULL. - - - - - - - Flags used in g_dbus_connection_call() and similar APIs. - - No flags set. - - - The bus must not launch -an owner for the destination name in response to this method -invocation. - - - the caller is prepared to -wait for interactive authorization. Since 2.46. - - - - Capabilities negotiated with the remote peer. - - No flags set. - - - The connection -supports exchanging UNIX file descriptors with the remote peer. - - - - The #GDBusConnection type is used for D-Bus connections to remote -peers such as a message buses. It is a low-level API that offers a -lot of flexibility. For instance, it lets you establish a connection -over any transport that can by represented as a #GIOStream. - -This class is rarely used directly in D-Bus clients. If you are writing -a D-Bus client, it is often easier to use the g_bus_own_name(), -g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. - -As an exception to the usual GLib rule that a particular object must not -be used by two threads at the same time, #GDBusConnection's methods may be -called from any thread. This is so that g_bus_get() and g_bus_get_sync() -can safely return the same #GDBusConnection when called from any thread. - -Most of the ways to obtain a #GDBusConnection automatically initialize it -(i.e. connect to D-Bus): for instance, g_dbus_connection_new() and -g_bus_get(), and the synchronous versions of those methods, give you an -initialized connection. Language bindings for GIO should use -g_initable_new() or g_async_initable_new_async(), which also initialize the -connection. - -If you construct an uninitialized #GDBusConnection, such as via -g_object_new(), you must initialize it via g_initable_init() or -g_async_initable_init_async() before using its methods or properties. -Calling methods or accessing properties on a #GDBusConnection that has not -completed initialization successfully is considered to be invalid, and leads -to undefined behaviour. In particular, if initialization fails with a -#GError, the only valid thing you can do with that #GDBusConnection is to -free it with g_object_unref(). - -## An example D-Bus server # {#gdbus-server} - -Here is an example for a D-Bus server: -[gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) - -## An example for exporting a subtree # {#gdbus-subtree-server} - -Here is an example for exporting a subtree: -[gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) - -## An example for file descriptor passing # {#gdbus-unix-fd-client} - -Here is an example for passing UNIX file descriptors: -[gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c) - -## An example for exporting a GObject # {#gdbus-export} - -Here is an example for exporting a #GObject: -[gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c) - - - - Finishes an operation started with g_dbus_connection_new(). - - - a #GDBusConnection or %NULL if @error is set. Free - with g_object_unref(). - - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback - passed to g_dbus_connection_new(). - - - - - - Finishes an operation started with g_dbus_connection_new_for_address(). - - - a #GDBusConnection or %NULL if @error is set. Free with - g_object_unref(). - - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed - to g_dbus_connection_new() - - - - - - Synchronously connects and sets up a D-Bus client connection for -exchanging D-Bus messages with an endpoint specified by @address -which must be in the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -This constructor can only be used to initiate client-side -connections - use g_dbus_connection_new_sync() if you need to act -as the server. In particular, @flags cannot contain the -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. - -This is a synchronous failable constructor. See -g_dbus_connection_new_for_address() for the asynchronous version. - -If @observer is not %NULL it may be used to control the -authentication process. - - - a #GDBusConnection or %NULL if @error is set. Free with - g_object_unref(). - - - - - a D-Bus address - - - - flags describing how to make the connection - - - - a #GDBusAuthObserver or %NULL - - - - a #GCancellable or %NULL - - - - - - Synchronously sets up a D-Bus connection for exchanging D-Bus messages -with the end represented by @stream. - -If @stream is a #GSocketConnection, then the corresponding #GSocket -will be put into non-blocking mode. - -The D-Bus connection will interact with @stream from a worker thread. -As a result, the caller should not interact with @stream after this -method has been called, except by calling g_object_unref() on it. - -If @observer is not %NULL it may be used to control the -authentication process. - -This is a synchronous failable constructor. See -g_dbus_connection_new() for the asynchronous version. - - - a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). - - - - - a #GIOStream - - - - the GUID to use if authenticating as a server or %NULL - - - - flags describing how to make the connection - - - - a #GDBusAuthObserver or %NULL - - - - a #GCancellable or %NULL - - - - - - Asynchronously sets up a D-Bus connection for exchanging D-Bus messages -with the end represented by @stream. - -If @stream is a #GSocketConnection, then the corresponding #GSocket -will be put into non-blocking mode. - -The D-Bus connection will interact with @stream from a worker thread. -As a result, the caller should not interact with @stream after this -method has been called, except by calling g_object_unref() on it. - -If @observer is not %NULL it may be used to control the -authentication process. - -When the operation is finished, @callback will be invoked. You can -then call g_dbus_connection_new_finish() to get the result of the -operation. - -This is an asynchronous failable constructor. See -g_dbus_connection_new_sync() for the synchronous -version. - - - - - - - a #GIOStream - - - - the GUID to use if authenticating as a server or %NULL - - - - flags describing how to make the connection - - - - a #GDBusAuthObserver or %NULL - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to @callback - - - - - - Asynchronously connects and sets up a D-Bus client connection for -exchanging D-Bus messages with an endpoint specified by @address -which must be in the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -This constructor can only be used to initiate client-side -connections - use g_dbus_connection_new() if you need to act as the -server. In particular, @flags cannot contain the -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. - -When the operation is finished, @callback will be invoked. You can -then call g_dbus_connection_new_for_address_finish() to get the result of -the operation. - -If @observer is not %NULL it may be used to control the -authentication process. - -This is an asynchronous failable constructor. See -g_dbus_connection_new_for_address_sync() for the synchronous -version. - - - - - - - a D-Bus address - - - - flags describing how to make the connection - - - - a #GDBusAuthObserver or %NULL - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to @callback - - - - - - Adds a message filter. Filters are handlers that are run on all -incoming and outgoing messages, prior to standard dispatch. Filters -are run in the order that they were added. The same handler can be -added as a filter more than once, in which case it will be run more -than once. Filters added during a filter callback won't be run on -the message being processed. Filter functions are allowed to modify -and even drop messages. - -Note that filters are run in a dedicated message handling thread so -they can't block and, generally, can't do anything but signal a -worker thread. Also note that filters are rarely needed - use API -such as g_dbus_connection_send_message_with_reply(), -g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead. - -If a filter consumes an incoming message the message is not -dispatched anywhere else - not even the standard dispatch machinery -(that API such as g_dbus_connection_signal_subscribe() and -g_dbus_connection_send_message_with_reply() relies on) will see the -message. Similarly, if a filter consumes an outgoing message, the -message will not be sent to the other peer. - -If @user_data_free_func is non-%NULL, it will be called (in the -thread-default main context of the thread you are calling this -method from) at some point after @user_data is no longer -needed. (It is not guaranteed to be called synchronously when the -filter is removed, and may be called after @connection has been -destroyed.) - - - a filter identifier that can be used with - g_dbus_connection_remove_filter() - - - - - a #GDBusConnection - - - - a filter function - - - - user data to pass to @filter_function - - - - function to free @user_data with when filter - is removed or %NULL - - - - - - Asynchronously invokes the @method_name method on the -@interface_name D-Bus interface on the remote object at -@object_path owned by @bus_name. - -If @connection is closed then the operation will fail with -%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will -fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value -not compatible with the D-Bus protocol, the operation fails with -%G_IO_ERROR_INVALID_ARGUMENT. - -If @reply_type is non-%NULL then the reply will be checked for having this type and an -error will be raised if it does not match. Said another way, if you give a @reply_type -then any non-%NULL return value will be of this type. Unless it’s -%G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more -values. - -If the @parameters #GVariant is floating, it is consumed. This allows -convenient 'inline' use of g_variant_new(), e.g.: -|[<!-- language="C" --> - g_dbus_connection_call (connection, - "org.freedesktop.StringThings", - "/org/freedesktop/StringThings", - "org.freedesktop.StringThings", - "TwoStrings", - g_variant_new ("(ss)", - "Thing One", - "Thing Two"), - NULL, - G_DBUS_CALL_FLAGS_NONE, - -1, - NULL, - (GAsyncReadyCallback) two_strings_done, - NULL); -]| - -This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can then call -g_dbus_connection_call_finish() to get the result of the operation. -See g_dbus_connection_call_sync() for the synchronous version of this -function. - -If @callback is %NULL then the D-Bus method call message will be sent with -the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - - - - - - - a #GDBusConnection - - - - a unique or well-known bus name or %NULL if - @connection is not a message bus connection - - - - path of remote object - - - - D-Bus interface to invoke method on - - - - the name of the method to invoke - - - - a #GVariant tuple with parameters for the method - or %NULL if not passing parameters - - - - the expected type of the reply (which will be a - tuple), or %NULL - - - - flags from the #GDBusCallFlags enumeration - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request - is satisfied or %NULL if you don't care about the result of the - method invocation - - - - the data to pass to @callback - - - - - - Finishes an operation started with g_dbus_connection_call(). - - - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). - - - - - a #GDBusConnection - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() - - - - - - Synchronously invokes the @method_name method on the -@interface_name D-Bus interface on the remote object at -@object_path owned by @bus_name. - -If @connection is closed then the operation will fail with -%G_IO_ERROR_CLOSED. If @cancellable is canceled, the -operation will fail with %G_IO_ERROR_CANCELLED. If @parameters -contains a value not compatible with the D-Bus protocol, the operation -fails with %G_IO_ERROR_INVALID_ARGUMENT. - -If @reply_type is non-%NULL then the reply will be checked for having -this type and an error will be raised if it does not match. Said -another way, if you give a @reply_type then any non-%NULL return -value will be of this type. - -If the @parameters #GVariant is floating, it is consumed. -This allows convenient 'inline' use of g_variant_new(), e.g.: -|[<!-- language="C" --> - g_dbus_connection_call_sync (connection, - "org.freedesktop.StringThings", - "/org/freedesktop/StringThings", - "org.freedesktop.StringThings", - "TwoStrings", - g_variant_new ("(ss)", - "Thing One", - "Thing Two"), - NULL, - G_DBUS_CALL_FLAGS_NONE, - -1, - NULL, - &error); -]| - -The calling thread is blocked until a reply is received. See -g_dbus_connection_call() for the asynchronous version of -this method. - - - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). - - - - - a #GDBusConnection - - - - a unique or well-known bus name or %NULL if - @connection is not a message bus connection - - - - path of remote object - - - - D-Bus interface to invoke method on - - - - the name of the method to invoke - - - - a #GVariant tuple with parameters for the method - or %NULL if not passing parameters - - - - the expected type of the reply, or %NULL - - - - flags from the #GDBusCallFlags enumeration - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - a #GCancellable or %NULL - - - - - - Like g_dbus_connection_call() but also takes a #GUnixFDList object. - -This method is only available on UNIX. - - - - - - - a #GDBusConnection - - - - a unique or well-known bus name or %NULL if - @connection is not a message bus connection - - - - path of remote object - - - - D-Bus interface to invoke method on - - - - the name of the method to invoke - - - - a #GVariant tuple with parameters for the method - or %NULL if not passing parameters - - - - the expected type of the reply, or %NULL - - - - flags from the #GDBusCallFlags enumeration - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - a #GUnixFDList or %NULL - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request is - satisfied or %NULL if you don't * care about the result of the - method invocation - - - - The data to pass to @callback. - - - - - - Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). - - - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). - - - - - a #GDBusConnection - - - - return location for a #GUnixFDList or %NULL - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed to - g_dbus_connection_call_with_unix_fd_list() - - - - - - Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. - -This method is only available on UNIX. - - - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). - - - - - a #GDBusConnection - - - - a unique or well-known bus name or %NULL - if @connection is not a message bus connection - - - - path of remote object - - - - D-Bus interface to invoke method on - - - - the name of the method to invoke - - - - a #GVariant tuple with parameters for - the method or %NULL if not passing parameters - - - - the expected type of the reply, or %NULL - - - - flags from the #GDBusCallFlags enumeration - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - a #GUnixFDList or %NULL - - - - return location for a #GUnixFDList or %NULL - - - - a #GCancellable or %NULL - - - - - - Closes @connection. Note that this never causes the process to -exit (this might only happen if the other end of a shared message -bus connection disconnects, see #GDBusConnection:exit-on-close). - -Once the connection is closed, operations such as sending a message -will return with the error %G_IO_ERROR_CLOSED. Closing a connection -will not automatically flush the connection so queued messages may -be lost. Use g_dbus_connection_flush() if you need such guarantees. - -If @connection is already closed, this method fails with -%G_IO_ERROR_CLOSED. - -When @connection has been closed, the #GDBusConnection::closed -signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that @connection was constructed in. - -This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can -then call g_dbus_connection_close_finish() to get the result of the -operation. See g_dbus_connection_close_sync() for the synchronous -version. - - - - - - - a #GDBusConnection - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request is - satisfied or %NULL if you don't care about the result - - - - The data to pass to @callback - - - - - - Finishes an operation started with g_dbus_connection_close(). - - - %TRUE if the operation succeeded, %FALSE if @error is set - - - - - a #GDBusConnection - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed - to g_dbus_connection_close() - - - - - - Synchronously closes @connection. The calling thread is blocked -until this is done. See g_dbus_connection_close() for the -asynchronous version of this method and more details about what it -does. - - - %TRUE if the operation succeeded, %FALSE if @error is set - - - - - a #GDBusConnection - - - - a #GCancellable or %NULL - - - - - - Emits a signal. - -If the parameters GVariant is floating, it is consumed. - -This can only fail if @parameters is not compatible with the D-Bus protocol -(%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed -(%G_IO_ERROR_CLOSED). - - - %TRUE unless @error is set - - - - - a #GDBusConnection - - - - the unique bus name for the destination - for the signal or %NULL to emit to all listeners - - - - path of remote object - - - - D-Bus interface to emit a signal on - - - - the name of the signal to emit - - - - a #GVariant tuple with parameters for the signal - or %NULL if not passing parameters - - - - - - Exports @action_group on @connection at @object_path. - -The implemented D-Bus API should be considered private. It is -subject to change in the future. - -A given object path can only have one action group exported on it. -If this constraint is violated, the export will fail and 0 will be -returned (with @error set accordingly). - -You can unexport the action group using -g_dbus_connection_unexport_action_group() with the return value of -this function. - -The thread default main context is taken at the time of this call. -All incoming action activations and state change requests are -reported from this context. Any changes on the action group that -cause it to emit signals must also come from this same context. -Since incoming action activations and state change requests are -rather likely to cause changes on the action group, this effectively -limits a given action group to being exported from only one main -context. - - - the ID of the export (never zero), or 0 in case of failure - - - - - a #GDBusConnection - - - - a D-Bus object path - - - - a #GActionGroup - - - - - - Exports @menu on @connection at @object_path. - -The implemented D-Bus API should be considered private. -It is subject to change in the future. - -An object path can only have one menu model exported on it. If this -constraint is violated, the export will fail and 0 will be -returned (with @error set accordingly). - -You can unexport the menu model using -g_dbus_connection_unexport_menu_model() with the return value of -this function. - - - the ID of the export (never zero), or 0 in case of failure - - - - - a #GDBusConnection - - - - a D-Bus object path - - - - a #GMenuModel - - - - - - Asynchronously flushes @connection, that is, writes all queued -outgoing message to the transport and then flushes the transport -(using g_output_stream_flush_async()). This is useful in programs -that wants to emit a D-Bus signal and then exit immediately. Without -flushing the connection, there is no guaranteed that the message has -been sent to the networking buffers in the OS kernel. - -This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can -then call g_dbus_connection_flush_finish() to get the result of the -operation. See g_dbus_connection_flush_sync() for the synchronous -version. - - - - - - - a #GDBusConnection - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the - request is satisfied or %NULL if you don't care about the result - - - - The data to pass to @callback - - - - - - Finishes an operation started with g_dbus_connection_flush(). - - - %TRUE if the operation succeeded, %FALSE if @error is set - - - - - a #GDBusConnection - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed - to g_dbus_connection_flush() - - - - - - Synchronously flushes @connection. The calling thread is blocked -until this is done. See g_dbus_connection_flush() for the -asynchronous version of this method and more details about what it -does. - - - %TRUE if the operation succeeded, %FALSE if @error is set - - - - - a #GDBusConnection - - - - a #GCancellable or %NULL - - - - - - Gets the capabilities negotiated with the remote peer - - - zero or more flags from the #GDBusCapabilityFlags enumeration - - - - - a #GDBusConnection - - - - - - Gets whether the process is terminated when @connection is -closed by the remote peer. See -#GDBusConnection:exit-on-close for more details. - - - whether the process is terminated when @connection is - closed by the remote peer - - - - - a #GDBusConnection - - - - - - Gets the flags used to construct this connection - - - zero or more flags from the #GDBusConnectionFlags enumeration - - - - - a #GDBusConnection - - - - - - The GUID of the peer performing the role of server when -authenticating. See #GDBusConnection:guid for more details. - - - The GUID. Do not free this string, it is owned by - @connection. - - - - - a #GDBusConnection - - - - - - Retrieves the last serial number assigned to a #GDBusMessage on -the current thread. This includes messages sent via both low-level -API such as g_dbus_connection_send_message() as well as -high-level API such as g_dbus_connection_emit_signal(), -g_dbus_connection_call() or g_dbus_proxy_call(). - - - the last used serial or zero when no message has been sent - within the current thread - - - - - a #GDBusConnection - - - - - - Gets the credentials of the authenticated peer. This will always -return %NULL unless @connection acted as a server -(e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) -when set up and the client passed credentials as part of the -authentication process. - -In a message bus setup, the message bus is always the server and -each application is a client. So this method will always return -%NULL for message bus clients. - - - a #GCredentials or %NULL if not - available. Do not free this object, it is owned by @connection. - - - - - a #GDBusConnection - - - - - - Gets the underlying stream used for IO. - -While the #GDBusConnection is active, it will interact with this -stream from a worker thread, so it is not safe to interact with -the stream directly. - - - the stream used for IO - - - - - a #GDBusConnection - - - - - - Gets the unique name of @connection as assigned by the message -bus. This can also be used to figure out if @connection is a -message bus connection. - - - the unique name or %NULL if @connection is not a message - bus connection. Do not free this string, it is owned by - @connection. - - - - - a #GDBusConnection - - - - - - Gets whether @connection is closed. - - - %TRUE if the connection is closed, %FALSE otherwise - - - - - a #GDBusConnection - - - - - - Registers callbacks for exported objects at @object_path with the -D-Bus interface that is described in @interface_info. - -Calls to functions in @vtable (and @user_data_free_func) will happen -in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. - -Note that all #GVariant values passed to functions in @vtable will match -the signature given in @interface_info - if a remote caller passes -incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` -is returned to the remote caller. - -Additionally, if the remote caller attempts to invoke methods or -access properties not mentioned in @interface_info the -`org.freedesktop.DBus.Error.UnknownMethod` resp. -`org.freedesktop.DBus.Error.InvalidArgs` errors -are returned to the caller. - -It is considered a programming error if the -#GDBusInterfaceGetPropertyFunc function in @vtable returns a -#GVariant of incorrect type. - -If an existing callback is already registered at @object_path and -@interface_name, then @error is set to #G_IO_ERROR_EXISTS. - -GDBus automatically implements the standard D-Bus interfaces -org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable -and org.freedesktop.Peer, so you don't have to implement those for the -objects you export. You can implement org.freedesktop.DBus.Properties -yourself, e.g. to handle getting and setting of properties asynchronously. - -Note that the reference count on @interface_info will be -incremented by 1 (unless allocated statically, e.g. if the -reference count is -1, see g_dbus_interface_info_ref()) for as long -as the object is exported. Also note that @vtable will be copied. - -See this [server][gdbus-server] for an example of how to use this method. - - - 0 if @error is set, otherwise a registration id (never 0) - that can be used with g_dbus_connection_unregister_object() - - - - - a #GDBusConnection - - - - the object path to register at - - - - introspection data for the interface - - - - a #GDBusInterfaceVTable to call into or %NULL - - - - data to pass to functions in @vtable - - - - function to call when the object path is unregistered - - - - - - Version of g_dbus_connection_register_object() using closures instead of a -#GDBusInterfaceVTable for easier binding in other languages. - - - 0 if @error is set, otherwise a registration id (never 0) -that can be used with g_dbus_connection_unregister_object() . - - - - - A #GDBusConnection. - - - - The object path to register at. - - - - Introspection data for the interface. - - - - #GClosure for handling incoming method calls. - - - - #GClosure for getting a property. - - - - #GClosure for setting a property. - - - - - - Registers a whole subtree of dynamic objects. - -The @enumerate and @introspection functions in @vtable are used to -convey, to remote callers, what nodes exist in the subtree rooted -by @object_path. - -When handling remote calls into any node in the subtree, first the -@enumerate function is used to check if the node exists. If the node exists -or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set -the @introspection function is used to check if the node supports the -requested method. If so, the @dispatch function is used to determine -where to dispatch the call. The collected #GDBusInterfaceVTable and -#gpointer will be used to call into the interface vtable for processing -the request. - -All calls into user-provided code will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. - -If an existing subtree is already registered at @object_path or -then @error is set to #G_IO_ERROR_EXISTS. - -Note that it is valid to register regular objects (using -g_dbus_connection_register_object()) in a subtree registered with -g_dbus_connection_register_subtree() - if so, the subtree handler -is tried as the last resort. One way to think about a subtree -handler is to consider it a fallback handler for object paths not -registered via g_dbus_connection_register_object() or other bindings. - -Note that @vtable will be copied so you cannot change it after -registration. - -See this [server][gdbus-subtree-server] for an example of how to use -this method. - - - 0 if @error is set, otherwise a subtree registration id (never 0) -that can be used with g_dbus_connection_unregister_subtree() . - - - - - a #GDBusConnection - - - - the object path to register the subtree at - - - - a #GDBusSubtreeVTable to enumerate, introspect and - dispatch nodes in the subtree - - - - flags used to fine tune the behavior of the subtree - - - - data to pass to functions in @vtable - - - - function to call when the subtree is unregistered - - - - - - Removes a filter. - -Note that since filters run in a different thread, there is a race -condition where it is possible that the filter will be running even -after calling g_dbus_connection_remove_filter(), so you cannot just -free data that the filter might be using. Instead, you should pass -a #GDestroyNotify to g_dbus_connection_add_filter(), which will be -called when it is guaranteed that the data is no longer needed. - - - - - - - a #GDBusConnection - - - - an identifier obtained from g_dbus_connection_add_filter() - - - - - - Asynchronously sends @message to the peer represented by @connection. - -Unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number -will be assigned by @connection and set on @message via -g_dbus_message_set_serial(). If @out_serial is not %NULL, then the -serial number used will be written to this location prior to -submitting the message to the underlying transport. - -If @connection is closed then the operation will fail with -%G_IO_ERROR_CLOSED. If @message is not well-formed, -the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] -for an example of how to use this low-level API to send and receive -UNIX file descriptors. - -Note that @message must be unlocked, unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - - - %TRUE if the message was well-formed and queued for - transmission, %FALSE if @error is set - - - - - a #GDBusConnection - - - - a #GDBusMessage - - - - flags affecting how the message is sent - - - - return location for serial number assigned - to @message when sending it or %NULL - - - - - - Asynchronously sends @message to the peer represented by @connection. - -Unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number -will be assigned by @connection and set on @message via -g_dbus_message_set_serial(). If @out_serial is not %NULL, then the -serial number used will be written to this location prior to -submitting the message to the underlying transport. - -If @connection is closed then the operation will fail with -%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will -fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, -the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - -This is an asynchronous method. When the operation is finished, @callback -will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can then call -g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. -See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. - -Note that @message must be unlocked, unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] -for an example of how to use this low-level API to send and receive -UNIX file descriptors. - - - - - - - a #GDBusConnection - - - - a #GDBusMessage - - - - flags affecting how the message is sent - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - return location for serial number assigned - to @message when sending it or %NULL - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request - is satisfied or %NULL if you don't care about the result - - - - The data to pass to @callback - - - - - - Finishes an operation started with g_dbus_connection_send_message_with_reply(). - -Note that @error is only set if a local in-process error -occurred. That is to say that the returned #GDBusMessage object may -be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use -g_dbus_message_to_gerror() to transcode this to a #GError. - -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] -for an example of how to use this low-level API to send and receive -UNIX file descriptors. - - - a locked #GDBusMessage or %NULL if @error is set - - - - - a #GDBusConnection - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed to - g_dbus_connection_send_message_with_reply() - - - - - - Synchronously sends @message to the peer represented by @connection -and blocks the calling thread until a reply is received or the -timeout is reached. See g_dbus_connection_send_message_with_reply() -for the asynchronous version of this method. - -Unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number -will be assigned by @connection and set on @message via -g_dbus_message_set_serial(). If @out_serial is not %NULL, then the -serial number used will be written to this location prior to -submitting the message to the underlying transport. - -If @connection is closed then the operation will fail with -%G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will -fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, -the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - -Note that @error is only set if a local in-process error -occurred. That is to say that the returned #GDBusMessage object may -be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use -g_dbus_message_to_gerror() to transcode this to a #GError. - -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] -for an example of how to use this low-level API to send and receive -UNIX file descriptors. - -Note that @message must be unlocked, unless @flags contain the -%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - - - a locked #GDBusMessage that is the reply - to @message or %NULL if @error is set - - - - - a #GDBusConnection - - - - a #GDBusMessage - - - - flags affecting how the message is sent. - - - - the timeout in milliseconds, -1 to use the default - timeout or %G_MAXINT for no timeout - - - - return location for serial number - assigned to @message when sending it or %NULL - - - - a #GCancellable or %NULL - - - - - - Sets whether the process should be terminated when @connection is -closed by the remote peer. See #GDBusConnection:exit-on-close for -more details. - -Note that this function should be used with care. Most modern UNIX -desktops tie the notion of a user session with the session bus, and expect -all of a user's applications to quit when their bus connection goes away. -If you are setting @exit_on_close to %FALSE for the shared session -bus connection, you should make sure that your application exits -when the user session ends. - - - - - - - a #GDBusConnection - - - - whether the process should be terminated - when @connection is closed by the remote peer - - - - - - Subscribes to signals on @connection and invokes @callback with a whenever -the signal is received. Note that @callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. - -If @connection is not a message bus connection, @sender must be -%NULL. - -If @sender is a well-known name note that @callback is invoked with -the unique name for the owner of @sender, not the well-known name -as one would expect. This is because the message bus rewrites the -name. As such, to avoid certain race conditions, users should be -tracking the name owner of the well-known name and use that when -processing the received signal. - -If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or -%G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is -interpreted as part of a namespace or path. The first argument -of a signal is matched against that part as specified by D-Bus. - -If @user_data_free_func is non-%NULL, it will be called (in the -thread-default main context of the thread you are calling this -method from) at some point after @user_data is no longer -needed. (It is not guaranteed to be called synchronously when the -signal is unsubscribed from, and may be called after @connection -has been destroyed.) - -As @callback is potentially invoked in a different thread from where it’s -emitted, it’s possible for this to happen after -g_dbus_connection_signal_unsubscribe() has been called in another thread. -Due to this, @user_data should have a strong reference which is freed with -@user_data_free_func, rather than pointing to data whose lifecycle is tied -to the signal subscription. For example, if a #GObject is used to store the -subscription ID from g_dbus_connection_signal_subscribe(), a strong reference -to that #GObject must be passed to @user_data, and g_object_unref() passed to -@user_data_free_func. You are responsible for breaking the resulting -reference count cycle by explicitly unsubscribing from the signal when -dropping the last external reference to the #GObject. Alternatively, a weak -reference may be used. - -It is guaranteed that if you unsubscribe from a signal using -g_dbus_connection_signal_unsubscribe() from the same thread which made the -corresponding g_dbus_connection_signal_subscribe() call, @callback will not -be invoked after g_dbus_connection_signal_unsubscribe() returns. - -The returned subscription identifier is an opaque value which is guaranteed -to never be zero. - -This function can never fail. - - - a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() - - - - - a #GDBusConnection - - - - sender name to match on (unique or well-known name) - or %NULL to listen from all senders - - - - D-Bus interface name to match on or %NULL to - match on all interfaces - - - - D-Bus signal name to match on or %NULL to match on - all signals - - - - object path to match on or %NULL to match on - all object paths - - - - contents of first string argument to match on or %NULL - to match on all kinds of arguments - - - - #GDBusSignalFlags describing how arg0 is used in subscribing to the - signal - - - - callback to invoke when there is a signal matching the requested data - - - - user data to pass to @callback - - - - function to free @user_data with when - subscription is removed or %NULL - - - - - - Unsubscribes from signals. - -Note that there may still be D-Bus traffic to process (relating to this -signal subscription) in the current thread-default #GMainContext after this -function has returned. You should continue to iterate the #GMainContext -until the #GDestroyNotify function passed to -g_dbus_connection_signal_subscribe() is called, in order to avoid memory -leaks through callbacks queued on the #GMainContext after it’s stopped being -iterated. - - - - - - - a #GDBusConnection - - - - a subscription id obtained from - g_dbus_connection_signal_subscribe() - - - - - - If @connection was created with -%G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method -starts processing messages. Does nothing on if @connection wasn't -created with this flag or if the method has already been called. - - - - - - - a #GDBusConnection - - - - - - Reverses the effect of a previous call to -g_dbus_connection_export_action_group(). - -It is an error to call this function with an ID that wasn't returned -from g_dbus_connection_export_action_group() or to call it with the -same ID more than once. - - - - - - - a #GDBusConnection - - - - the ID from g_dbus_connection_export_action_group() - - - - - - Reverses the effect of a previous call to -g_dbus_connection_export_menu_model(). - -It is an error to call this function with an ID that wasn't returned -from g_dbus_connection_export_menu_model() or to call it with the -same ID more than once. - - - - - - - a #GDBusConnection - - - - the ID from g_dbus_connection_export_menu_model() - - - - - - Unregisters an object. - - - %TRUE if the object was unregistered, %FALSE otherwise - - - - - a #GDBusConnection - - - - a registration id obtained from - g_dbus_connection_register_object() - - - - - - Unregisters a subtree. - - - %TRUE if the subtree was unregistered, %FALSE otherwise - - - - - a #GDBusConnection - - - - a subtree registration id obtained from - g_dbus_connection_register_subtree() - - - - - - A D-Bus address specifying potential endpoints that can be used -when establishing the connection. - - - - A #GDBusAuthObserver object to assist in the authentication process or %NULL. - - - - Flags from the #GDBusCapabilityFlags enumeration -representing connection features negotiated with the other peer. - - - - A boolean specifying whether the connection has been closed. - - - - A boolean specifying whether the process will be terminated (by -calling `raise(SIGTERM)`) if the connection is closed by the -remote peer. - -Note that #GDBusConnection objects returned by g_bus_get_finish() -and g_bus_get_sync() will (usually) have this property set to %TRUE. - - - - Flags from the #GDBusConnectionFlags enumeration. - - - - The GUID of the peer performing the role of server when -authenticating. - -If you are constructing a #GDBusConnection and pass -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the -#GDBusConnection:flags property then you MUST also set this -property to a valid guid. - -If you are constructing a #GDBusConnection and pass -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the -#GDBusConnection:flags property you will be able to read the GUID -of the other peer here after the connection has been successfully -initialized. - - - - The underlying #GIOStream used for I/O. - -If this is passed on construction and is a #GSocketConnection, -then the corresponding #GSocket will be put into non-blocking mode. - -While the #GDBusConnection is active, it will interact with this -stream from a worker thread, so it is not safe to interact with -the stream directly. - - - - The unique name as assigned by the message bus or %NULL if the -connection is not open or not a message bus connection. - - - - Emitted when the connection is closed. - -The cause of this event can be - -- If g_dbus_connection_close() is called. In this case - @remote_peer_vanished is set to %FALSE and @error is %NULL. - -- If the remote peer closes the connection. In this case - @remote_peer_vanished is set to %TRUE and @error is set. - -- If the remote peer sends invalid or malformed data. In this - case @remote_peer_vanished is set to %FALSE and @error is set. - -Upon receiving this signal, you should give up your reference to -@connection. You are guaranteed that this signal is emitted only -once. - - - - - - %TRUE if @connection is closed because the - remote peer closed its end of the connection - - - - a #GError with more details about the event or %NULL - - - - - - - Flags used when creating a new #GDBusConnection. - - No flags set. - - - Perform authentication against server. - - - Perform authentication against client. - - - When -authenticating as a server, allow the anonymous authentication -method. - - - Pass this flag if connecting to a peer that is a -message bus. This means that the Hello() method will be invoked as part of the connection setup. - - - If set, processing of D-Bus messages is -delayed until g_dbus_connection_start_message_processing() is called. - - - - Error codes for the %G_DBUS_ERROR error domain. - - A generic error; "something went wrong" - see the error message for -more. - - - There was not enough memory to complete an operation. - - - The bus doesn't know how to launch a service to supply the bus name -you wanted. - - - The bus name you referenced doesn't exist (i.e. no application owns -it). - - - No reply to a message expecting one, usually means a timeout occurred. - - - Something went wrong reading or writing to a socket, for example. - - - A D-Bus bus address was malformed. - - - Requested operation isn't supported (like ENOSYS on UNIX). - - - Some limited resource is exhausted. - - - Security restrictions don't allow doing what you're trying to do. - - - Authentication didn't work. - - - Unable to connect to server (probably caused by ECONNREFUSED on a -socket). - - - Certain timeout errors, possibly ETIMEDOUT on a socket. Note that -%G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: -this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also -exists. We can't fix it for compatibility reasons so just be -careful. - - - No network access (probably ENETUNREACH on a socket). - - - Can't bind a socket since its address is in use (i.e. EADDRINUSE). - - - The connection is disconnected and you're trying to use it. - - - Invalid arguments passed to a method call. - - - Missing file. - - - Existing file and the operation you're using does not silently overwrite. - - - Method name you invoked isn't known by the object you invoked it on. - - - Certain timeout errors, e.g. while starting a service. Warning: this is -confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We -can't fix it for compatibility reasons so just be careful. - - - Tried to remove or modify a match rule that didn't exist. - - - The match rule isn't syntactically valid. - - - While starting a new process, the exec() call failed. - - - While starting a new process, the fork() call failed. - - - While starting a new process, the child exited with a status code. - - - While starting a new process, the child exited on a signal. - - - While starting a new process, something went wrong. - - - We failed to setup the environment correctly. - - - We failed to setup the config parser correctly. - - - Bus name was not valid. - - - Service file not found in system-services directory. - - - Permissions are incorrect on the setuid helper. - - - Service file invalid (Name, User or Exec missing). - - - Tried to get a UNIX process ID and it wasn't available. - - - Tried to get a UNIX process ID and it wasn't available. - - - A type signature is not valid. - - - A file contains invalid syntax or is otherwise broken. - - - Asked for SELinux security context and it wasn't available. - - - Asked for ADT audit data and it wasn't available. - - - There's already an object with the requested object path. - - - Object you invoked a method on isn't known. Since 2.42 - - - Interface you invoked a method on isn't known by the object. Since 2.42 - - - Property you tried to access isn't known by the object. Since 2.42 - - - Property you tried to set is read-only. Since 2.42 - - - Creates a D-Bus error name to use for @error. If @error matches -a registered error (cf. g_dbus_error_register_error()), the corresponding -D-Bus error name will be returned. - -Otherwise the a name of the form -`org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` -will be used. This allows other GDBus applications to map the error -on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). - -This function is typically only used in object mappings to put a -#GError on the wire. Regular applications should not use it. - - - A D-Bus error name (never %NULL). Free with g_free(). - - - - - A #GError. - - - - - - Gets the D-Bus error name used for @error, if any. - -This function is guaranteed to return a D-Bus error name for all -#GErrors returned from functions handling remote method calls -(e.g. g_dbus_connection_call_finish()) unless -g_dbus_error_strip_remote_error() has been used on @error. - - - an allocated string or %NULL if the D-Bus error name - could not be found. Free with g_free(). - - - - - a #GError - - - - - - Checks if @error represents an error received via D-Bus from a remote peer. If so, -use g_dbus_error_get_remote_error() to get the name of the error. - - - %TRUE if @error represents an error from a remote peer, -%FALSE otherwise. - - - - - A #GError. - - - - - - Creates a #GError based on the contents of @dbus_error_name and -@dbus_error_message. - -Errors registered with g_dbus_error_register_error() will be looked -up using @dbus_error_name and if a match is found, the error domain -and code is used. Applications can use g_dbus_error_get_remote_error() -to recover @dbus_error_name. - -If a match against a registered error is not found and the D-Bus -error name is in a form as returned by g_dbus_error_encode_gerror() -the error domain and code encoded in the name is used to -create the #GError. Also, @dbus_error_name is added to the error message -such that it can be recovered with g_dbus_error_get_remote_error(). - -Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR -in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is -added to the error message such that it can be recovered with -g_dbus_error_get_remote_error(). - -In all three cases, @dbus_error_name can always be recovered from the -returned #GError using the g_dbus_error_get_remote_error() function -(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). - -This function is typically only used in object mappings to prepare -#GError instances for applications. Regular applications should not use -it. - - - An allocated #GError. Free with g_error_free(). - - - - - D-Bus error name. - - - - D-Bus error message. - - - - - - - - - - - Creates an association to map between @dbus_error_name and -#GErrors specified by @error_domain and @error_code. - -This is typically done in the routine that returns the #GQuark for -an error domain. - - - %TRUE if the association was created, %FALSE if it already -exists. - - - - - A #GQuark for an error domain. - - - - An error code. - - - - A D-Bus error name. - - - - - - Helper function for associating a #GError error domain with D-Bus error names. - - - - - - - The error domain name. - - - - A pointer where to store the #GQuark. - - - - A pointer to @num_entries #GDBusErrorEntry struct items. - - - - - - Number of items to register. - - - - - - Does nothing if @error is %NULL. Otherwise sets *@error to -a new #GError created with g_dbus_error_new_for_dbus_error() -with @dbus_error_message prepend with @format (unless %NULL). - - - - - - - A pointer to a #GError or %NULL. - - - - D-Bus error name. - - - - D-Bus error message. - - - - printf()-style format to prepend to @dbus_error_message or %NULL. - - - - Arguments for @format. - - - - - - Like g_dbus_error_set_dbus_error() but intended for language bindings. - - - - - - - A pointer to a #GError or %NULL. - - - - D-Bus error name. - - - - D-Bus error message. - - - - printf()-style format to prepend to @dbus_error_message or %NULL. - - - - Arguments for @format. - - - - - - Looks for extra information in the error message used to recover -the D-Bus error name and strips it if found. If stripped, the -message field in @error will correspond exactly to what was -received on the wire. - -This is typically used when presenting errors to the end user. - - - %TRUE if information was stripped, %FALSE otherwise. - - - - - A #GError. - - - - - - Destroys an association previously set up with g_dbus_error_register_error(). - - - %TRUE if the association was destroyed, %FALSE if it wasn't found. - - - - - A #GQuark for an error domain. - - - - An error code. - - - - A D-Bus error name. - - - - - - - Struct used in g_dbus_error_register_error_domain(). - - - An error code. - - - - The D-Bus error name to associate with @error_code. - - - - - The #GDBusInterface type is the base type for D-Bus interfaces both -on the service side (see #GDBusInterfaceSkeleton) and client side -(see #GDBusProxy). - - - Gets the #GDBusObject that @interface_ belongs to, if any. - - - A #GDBusObject or %NULL. The returned -reference should be freed with g_object_unref(). - - - - - An exported D-Bus interface. - - - - - - Gets D-Bus introspection information for the D-Bus interface -implemented by @interface_. - - - A #GDBusInterfaceInfo. Do not free. - - - - - An exported D-Bus interface. - - - - - - Gets the #GDBusObject that @interface_ belongs to, if any. - -It is not safe to use the returned object if @interface_ or -the returned object is being used from other threads. See -g_dbus_interface_dup_object() for a thread-safe alternative. - - - A #GDBusObject or %NULL. The returned - reference belongs to @interface_ and should not be freed. - - - - - An exported D-Bus interface - - - - - - Sets the #GDBusObject for @interface_ to @object. - -Note that @interface_ will hold a weak reference to @object. - - - - - - - An exported D-Bus interface. - - - - A #GDBusObject or %NULL. - - - - - - Gets the #GDBusObject that @interface_ belongs to, if any. - - - A #GDBusObject or %NULL. The returned -reference should be freed with g_object_unref(). - - - - - An exported D-Bus interface. - - - - - - Gets D-Bus introspection information for the D-Bus interface -implemented by @interface_. - - - A #GDBusInterfaceInfo. Do not free. - - - - - An exported D-Bus interface. - - - - - - Gets the #GDBusObject that @interface_ belongs to, if any. - -It is not safe to use the returned object if @interface_ or -the returned object is being used from other threads. See -g_dbus_interface_dup_object() for a thread-safe alternative. - - - A #GDBusObject or %NULL. The returned - reference belongs to @interface_ and should not be freed. - - - - - An exported D-Bus interface - - - - - - Sets the #GDBusObject for @interface_ to @object. - -Note that @interface_ will hold a weak reference to @object. - - - - - - - An exported D-Bus interface. - - - - A #GDBusObject or %NULL. - - - - - - - The type of the @get_property function in #GDBusInterfaceVTable. - - - A #GVariant with the value for @property_name or %NULL if - @error is set. If the returned #GVariant is floating, it is - consumed - otherwise its reference count is decreased by one. - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that the method was invoked on. - - - - The D-Bus interface name for the property. - - - - The name of the property to get the value of. - - - - Return location for error. - - - - The @user_data #gpointer passed to g_dbus_connection_register_object(). - - - - - - Base type for D-Bus interfaces. - - - The parent interface. - - - - - - - A #GDBusInterfaceInfo. Do not free. - - - - - An exported D-Bus interface. - - - - - - - - - - A #GDBusObject or %NULL. The returned - reference belongs to @interface_ and should not be freed. - - - - - An exported D-Bus interface - - - - - - - - - - - - - - An exported D-Bus interface. - - - - A #GDBusObject or %NULL. - - - - - - - - - - A #GDBusObject or %NULL. The returned -reference should be freed with g_object_unref(). - - - - - An exported D-Bus interface. - - - - - - - - Information about a D-Bus interface. - - - The reference count or -1 if statically allocated. - - - - The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". - - - - A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - Builds a lookup-cache to speed up -g_dbus_interface_info_lookup_method(), -g_dbus_interface_info_lookup_signal() and -g_dbus_interface_info_lookup_property(). - -If this has already been called with @info, the existing cache is -used and its use count is increased. - -Note that @info cannot be modified until -g_dbus_interface_info_cache_release() is called. - - - - - - - A #GDBusInterfaceInfo. - - - - - - Decrements the usage count for the cache for @info built by -g_dbus_interface_info_cache_build() (if any) and frees the -resources used by the cache if the usage count drops to zero. - - - - - - - A GDBusInterfaceInfo - - - - - - Appends an XML representation of @info (and its children) to @string_builder. - -This function is typically used for generating introspection XML -documents at run-time for handling the -`org.freedesktop.DBus.Introspectable.Introspect` -method. - - - - - - - A #GDBusNodeInfo - - - - Indentation level. - - - - A #GString to to append XML data to. - - - - - - Looks up information about a method. - -The cost of this function is O(n) in number of methods unless -g_dbus_interface_info_cache_build() has been used on @info. - - - A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. - - - - - A #GDBusInterfaceInfo. - - - - A D-Bus method name (typically in CamelCase) - - - - - - Looks up information about a property. - -The cost of this function is O(n) in number of properties unless -g_dbus_interface_info_cache_build() has been used on @info. - - - A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. - - - - - A #GDBusInterfaceInfo. - - - - A D-Bus property name (typically in CamelCase). - - - - - - Looks up information about a signal. - -The cost of this function is O(n) in number of signals unless -g_dbus_interface_info_cache_build() has been used on @info. - - - A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. - - - - - A #GDBusInterfaceInfo. - - - - A D-Bus signal name (typically in CamelCase) - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusInterfaceInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusInterfaceInfo. - - - - - - - The type of the @method_call function in #GDBusInterfaceVTable. - - - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that the method was invoked on. - - - - The D-Bus interface name the method was invoked on. - - - - The name of the method that was invoked. - - - - A #GVariant tuple with parameters. - - - - A #GDBusMethodInvocation object that must be used to return a value or error. - - - - The @user_data #gpointer passed to g_dbus_connection_register_object(). - - - - - - The type of the @set_property function in #GDBusInterfaceVTable. - - - %TRUE if the property was set to @value, %FALSE if @error is set. - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that the method was invoked on. - - - - The D-Bus interface name for the property. - - - - The name of the property to get the value of. - - - - The value to set the property to. - - - - Return location for error. - - - - The @user_data #gpointer passed to g_dbus_connection_register_object(). - - - - - - Abstract base class for D-Bus interfaces on the service side. - - - - If @interface_ has outstanding changes, request for these changes to be -emitted immediately. - -For example, an exported D-Bus interface may queue up property -changes and emit the -`org.freedesktop.DBus.Properties.PropertiesChanged` -signal later (e.g. in an idle handler). This technique is useful -for collapsing multiple property changes into one. - - - - - - - A #GDBusInterfaceSkeleton. - - - - - - - - - - - - - - - - - - - - Gets D-Bus introspection information for the D-Bus interface -implemented by @interface_. - - - A #GDBusInterfaceInfo (never %NULL). Do not free. - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets all D-Bus properties for @interface_. - - - A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. -Free with g_variant_unref(). - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets the interface vtable for the D-Bus interface implemented by -@interface_. The returned function pointers should expect @interface_ -itself to be passed as @user_data. - - - A #GDBusInterfaceVTable (never %NULL). - - - - - A #GDBusInterfaceSkeleton. - - - - - - Exports @interface_ at @object_path on @connection. - -This can be called multiple times to export the same @interface_ -onto multiple connections however the @object_path provided must be -the same for all connections. - -Use g_dbus_interface_skeleton_unexport() to unexport the object. - - - %TRUE if the interface was exported on @connection, otherwise %FALSE with -@error set. - - - - - The D-Bus interface to export. - - - - A #GDBusConnection to export @interface_ on. - - - - The path to export the interface at. - - - - - - If @interface_ has outstanding changes, request for these changes to be -emitted immediately. - -For example, an exported D-Bus interface may queue up property -changes and emit the -`org.freedesktop.DBus.Properties.PropertiesChanged` -signal later (e.g. in an idle handler). This technique is useful -for collapsing multiple property changes into one. - - - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets the first connection that @interface_ is exported on, if any. - - - A #GDBusConnection or %NULL if @interface_ is -not exported anywhere. Do not free, the object belongs to @interface_. - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets a list of the connections that @interface_ is exported on. - - - A list of - all the connections that @interface_ is exported on. The returned - list should be freed with g_list_free() after each element has - been freed with g_object_unref(). - - - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior -of @interface_ - - - One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets D-Bus introspection information for the D-Bus interface -implemented by @interface_. - - - A #GDBusInterfaceInfo (never %NULL). Do not free. - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets the object path that @interface_ is exported on, if any. - - - A string owned by @interface_ or %NULL if @interface_ is not exported -anywhere. Do not free, the string belongs to @interface_. - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets all D-Bus properties for @interface_. - - - A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. -Free with g_variant_unref(). - - - - - A #GDBusInterfaceSkeleton. - - - - - - Gets the interface vtable for the D-Bus interface implemented by -@interface_. The returned function pointers should expect @interface_ -itself to be passed as @user_data. - - - A #GDBusInterfaceVTable (never %NULL). - - - - - A #GDBusInterfaceSkeleton. - - - - - - Checks if @interface_ is exported on @connection. - - - %TRUE if @interface_ is exported on @connection, %FALSE otherwise. - - - - - A #GDBusInterfaceSkeleton. - - - - A #GDBusConnection. - - - - - - Sets flags describing what the behavior of @skeleton should be. - - - - - - - A #GDBusInterfaceSkeleton. - - - - Flags from the #GDBusInterfaceSkeletonFlags enumeration. - - - - - - Stops exporting @interface_ on all connections it is exported on. - -To unexport @interface_ from only a single connection, use -g_dbus_interface_skeleton_unexport_from_connection() - - - - - - - A #GDBusInterfaceSkeleton. - - - - - - Stops exporting @interface_ on @connection. - -To stop exporting on all connections the interface is exported on, -use g_dbus_interface_skeleton_unexport(). - - - - - - - A #GDBusInterfaceSkeleton. - - - - A #GDBusConnection. - - - - - - Flags from the #GDBusInterfaceSkeletonFlags enumeration. - - - - - - - - - - Emitted when a method is invoked by a remote caller and used to -determine if the method call is authorized. - -Note that this signal is emitted in a thread dedicated to -handling the method call so handlers are allowed to perform -blocking IO. This means that it is appropriate to call e.g. -[polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) -with the -[POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) -flag set. - -If %FALSE is returned then no further handlers are run and the -signal handler must take a reference to @invocation and finish -handling the call (e.g. return an error via -g_dbus_method_invocation_return_error()). - -Otherwise, if %TRUE is returned, signal emission continues. If no -handlers return %FALSE, then the method is dispatched. If -@interface has an enclosing #GDBusObjectSkeleton, then the -#GDBusObjectSkeleton::authorize-method signal handlers run before -the handlers for this signal. - -The default class handler just returns %TRUE. - -Please note that the common case is optimized: if no signals -handlers are connected and the default class handler isn't -overridden (for both @interface and the enclosing -#GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does -not have the -%G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD -flags set, no dedicated thread is ever used and the call will be -handled in the same thread as the object that @interface belongs -to was exported in. - - %TRUE if the call is authorized, %FALSE otherwise. - - - - - A #GDBusMethodInvocation. - - - - - - - Class structure for #GDBusInterfaceSkeleton. - - - The parent class. - - - - - - - A #GDBusInterfaceInfo (never %NULL). Do not free. - - - - - A #GDBusInterfaceSkeleton. - - - - - - - - - - A #GDBusInterfaceVTable (never %NULL). - - - - - A #GDBusInterfaceSkeleton. - - - - - - - - - - A #GVariant of type -['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. -Free with g_variant_unref(). - - - - - A #GDBusInterfaceSkeleton. - - - - - - - - - - - - - - A #GDBusInterfaceSkeleton. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags describing the behavior of a #GDBusInterfaceSkeleton instance. - - No flags set. - - - Each method invocation is handled in - a thread dedicated to the invocation. This means that the method implementation can use blocking IO - without blocking any other part of the process. It also means that the method implementation must - use locking to access data structures used by other threads. - - - - - - - Virtual table for handling properties and method calls for a D-Bus -interface. - -Since 2.38, if you want to handle getting/setting D-Bus properties -asynchronously, give %NULL as your get_property() or set_property() -function. The D-Bus call will be directed to your @method_call function, -with the provided @interface_name set to "org.freedesktop.DBus.Properties". - -Ownership of the #GDBusMethodInvocation object passed to the -method_call() function is transferred to your handler; you must -call one of the methods of #GDBusMethodInvocation to return a reply -(possibly empty), or an error. These functions also take ownership -of the passed-in invocation object, so unless the invocation -object has otherwise been referenced, it will be then be freed. -Calling one of these functions may be done within your -method_call() implementation but it also can be done at a later -point to handle the method asynchronously. - -The usual checks on the validity of the calls is performed. For -`Get` calls, an error is automatically returned if the property does -not exist or the permissions do not allow access. The same checks are -performed for `Set` calls, and the provided value is also checked for -being the correct type. - -For both `Get` and `Set` calls, the #GDBusMethodInvocation -passed to the @method_call handler can be queried with -g_dbus_method_invocation_get_property_info() to get a pointer -to the #GDBusPropertyInfo of the property. - -If you have readable properties specified in your interface info, -you must ensure that you either provide a non-%NULL @get_property() -function or provide implementations of both the `Get` and `GetAll` -methods on org.freedesktop.DBus.Properties interface in your @method_call -function. Note that the required return type of the `Get` call is -`(v)`, not the type of the property. `GetAll` expects a return value -of type `a{sv}`. - -If you have writable properties specified in your interface info, -you must ensure that you either provide a non-%NULL @set_property() -function or provide an implementation of the `Set` call. If implementing -the call, you must return the value of type %G_VARIANT_TYPE_UNIT. - - - Function for handling incoming method calls. - - - - Function for getting a property. - - - - Function for setting a property. - - - - - - - - - - #GDBusMenuModel is an implementation of #GMenuModel that can be used -as a proxy for a menu model that is exported over D-Bus with -g_dbus_connection_export_menu_model(). - - Obtains a #GDBusMenuModel for the menu model which is exported -at the given @bus_name and @object_path. - -The thread default main context is taken at the time of this call. -All signals on the menu model (and any linked models) are reported -with respect to this context. All calls on the returned menu model -(and linked models) must also originate from this same context, with -the thread default main context unchanged. - - - a #GDBusMenuModel object. Free with - g_object_unref(). - - - - - a #GDBusConnection - - - - the bus name which exports the menu model - or %NULL if @connection is not a message bus connection - - - - the object path at which the menu model is exported - - - - - - - A type for representing D-Bus messages that can be sent or received -on a #GDBusConnection. - - Creates a new empty #GDBusMessage. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - Creates a new #GDBusMessage from the data stored at @blob. The byte -order that the message was in can be retrieved using -g_dbus_message_get_byte_order(). - -If the @blob cannot be parsed, contains invalid fields, or contains invalid -headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. - - - A new #GDBusMessage or %NULL if @error is set. Free with -g_object_unref(). - - - - - A blob representing a binary D-Bus message. - - - - - - The length of @blob. - - - - A #GDBusCapabilityFlags describing what protocol features are supported. - - - - - - Creates a new #GDBusMessage for a method call. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - A valid D-Bus name or %NULL. - - - - A valid object path. - - - - A valid D-Bus interface name or %NULL. - - - - A valid method name. - - - - - - Creates a new #GDBusMessage for a signal emission. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - A valid object path. - - - - A valid D-Bus interface name. - - - - A valid signal name. - - - - - - Utility function to calculate how many bytes are needed to -completely deserialize the D-Bus message stored at @blob. - - - Number of bytes needed or -1 if @error is set (e.g. if -@blob contains invalid data or not enough data is available to -determine the size). - - - - - A blob representing a binary D-Bus message. - - - - - - The length of @blob (must be at least 16). - - - - - - Copies @message. The copy is a deep copy and the returned -#GDBusMessage is completely identical except that it is guaranteed -to not be locked. - -This operation can fail if e.g. @message contains file descriptors -and the per-process or system-wide open files limit is reached. - - - A new #GDBusMessage or %NULL if @error is set. - Free with g_object_unref(). - - - - - A #GDBusMessage. - - - - - - Convenience to get the first item in the body of @message. - - - The string item or %NULL if the first item in the body of -@message is not a string. - - - - - A #GDBusMessage. - - - - - - Gets the body of a message. - - - A #GVariant or %NULL if the body is -empty. Do not free, it is owned by @message. - - - - - A #GDBusMessage. - - - - - - Gets the byte order of @message. - - - The byte order. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Gets the flags for @message. - - - Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). - - - - - A #GDBusMessage. - - - - - - Gets a header field on @message. - -The caller is responsible for checking the type of the returned #GVariant -matches what is expected. - - - A #GVariant with the value if the header was found, %NULL -otherwise. Do not free, it is owned by @message. - - - - - A #GDBusMessage. - - - - A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - - - - - - Gets an array of all header fields on @message that are set. - - - An array of header fields -terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element -is a #guchar. Free with g_free(). - - - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Checks whether @message is locked. To monitor changes to this -value, conncet to the #GObject::notify signal to listen for changes -on the #GDBusMessage:locked property. - - - %TRUE if @message is locked, %FALSE otherwise. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Gets the type of @message. - - - A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Gets the serial for @message. - - - A #guint32. - - - - - A #GDBusMessage. - - - - - - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. - - - The value. - - - - - A #GDBusMessage. - - - - - - Gets the UNIX file descriptors associated with @message, if any. - -This method is only available on UNIX. - - - A #GUnixFDList or %NULL if no file descriptors are -associated. Do not free, this object is owned by @message. - - - - - A #GDBusMessage. - - - - - - If @message is locked, does nothing. Otherwise locks the message. - - - - - - - A #GDBusMessage. - - - - - - Creates a new #GDBusMessage that is an error reply to @method_call_message. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to -create a reply message to. - - - - A valid D-Bus error name. - - - - The D-Bus error message in a printf() format. - - - - Arguments for @error_message_format. - - - - - - Creates a new #GDBusMessage that is an error reply to @method_call_message. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to -create a reply message to. - - - - A valid D-Bus error name. - - - - The D-Bus error message. - - - - - - Like g_dbus_message_new_method_error() but intended for language bindings. - - - A #GDBusMessage. Free with g_object_unref(). - - - - - A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to -create a reply message to. - - - - A valid D-Bus error name. - - - - The D-Bus error message in a printf() format. - - - - Arguments for @error_message_format. - - - - - - Creates a new #GDBusMessage that is a reply to @method_call_message. - - - #GDBusMessage. Free with g_object_unref(). - - - - - A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to -create a reply message to. - - - - - - Produces a human-readable multi-line description of @message. - -The contents of the description has no ABI guarantees, the contents -and formatting is subject to change at any time. Typical output -looks something like this: -|[ -Flags: none -Version: 0 -Serial: 4 -Headers: - path -> objectpath '/org/gtk/GDBus/TestObject' - interface -> 'org.gtk.GDBus.TestInterface' - member -> 'GimmeStdout' - destination -> ':1.146' -Body: () -UNIX File Descriptors: - (none) -]| -or -|[ -Flags: no-reply-expected -Version: 0 -Serial: 477 -Headers: - reply-serial -> uint32 4 - destination -> ':1.159' - sender -> ':1.146' - num-unix-fds -> uint32 1 -Body: () -UNIX File Descriptors: - fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 -]| - - - A string that should be freed with g_free(). - - - - - A #GDBusMessage. - - - - Indentation level. - - - - - - Sets the body @message. As a side-effect the -%G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the -type string of @body (or cleared if @body is %NULL). - -If @body is floating, @message assumes ownership of @body. - - - - - - - A #GDBusMessage. - - - - Either %NULL or a #GVariant that is a tuple. - - - - - - Sets the byte order of @message. - - - - - - - A #GDBusMessage. - - - - The byte order. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Sets the flags to set on @message. - - - - - - - A #GDBusMessage. - - - - Flags for @message that are set (typically values from the #GDBusMessageFlags -enumeration bitwise ORed together). - - - - - - Sets a header field on @message. - -If @value is floating, @message assumes ownership of @value. - - - - - - - A #GDBusMessage. - - - - A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - - - - A #GVariant to set the header field or %NULL to clear the header field. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Sets @message to be of @type. - - - - - - - A #GDBusMessage. - - - - A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Sets the serial for @message. - - - - - - - A #GDBusMessage. - - - - A #guint32. - - - - - - Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. - - - - - - - A #GDBusMessage. - - - - The value to set. - - - - - - Sets the UNIX file descriptors associated with @message. As a -side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header -field is set to the number of fds in @fd_list (or cleared if -@fd_list is %NULL). - -This method is only available on UNIX. - - - - - - - A #GDBusMessage. - - - - A #GUnixFDList or %NULL. - - - - - - Serializes @message to a blob. The byte order returned by -g_dbus_message_get_byte_order() will be used. - - - A pointer to a -valid binary D-Bus message of @out_size bytes generated by @message -or %NULL if @error is set. Free with g_free(). - - - - - - - A #GDBusMessage. - - - - Return location for size of generated blob. - - - - A #GDBusCapabilityFlags describing what protocol features are supported. - - - - - - If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does -nothing and returns %FALSE. - -Otherwise this method encodes the error in @message as a #GError -using g_dbus_error_set_dbus_error() using the information in the -%G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as -well as the first string item in @message's body. - - - %TRUE if @error was set, %FALSE otherwise. - - - - - A #GDBusMessage. - - - - - - - - - - Enumeration used to describe the byte order of a D-Bus message. - - The byte order is big endian. - - - The byte order is little endian. - - - - Signature for function used in g_dbus_connection_add_filter(). - -A filter function is passed a #GDBusMessage and expected to return -a #GDBusMessage too. Passive filter functions that don't modify the -message can simply return the @message object: -|[ -static GDBusMessage * -passive_filter (GDBusConnection *connection - GDBusMessage *message, - gboolean incoming, - gpointer user_data) -{ - // inspect @message - return message; -} -]| -Filter functions that wants to drop a message can simply return %NULL: -|[ -static GDBusMessage * -drop_filter (GDBusConnection *connection - GDBusMessage *message, - gboolean incoming, - gpointer user_data) -{ - if (should_drop_message) - { - g_object_unref (message); - message = NULL; - } - return message; -} -]| -Finally, a filter function may modify a message by copying it: -|[ -static GDBusMessage * -modifying_filter (GDBusConnection *connection - GDBusMessage *message, - gboolean incoming, - gpointer user_data) -{ - GDBusMessage *copy; - GError *error; - - error = NULL; - copy = g_dbus_message_copy (message, &error); - // handle @error being set - g_object_unref (message); - - // modify @copy - - return copy; -} -]| -If the returned #GDBusMessage is different from @message and cannot -be sent on @connection (it could use features, such as file -descriptors, not compatible with @connection), then a warning is -logged to standard error. Applications can -check this ahead of time using g_dbus_message_to_blob() passing a -#GDBusCapabilityFlags value obtained from @connection. - - - A #GDBusMessage that will be freed with -g_object_unref() or %NULL to drop the message. Passive filter -functions can simply return the passed @message object. - - - - - A #GDBusConnection. - - - - A locked #GDBusMessage that the filter function takes ownership of. - - - - %TRUE if it is a message received from the other peer, %FALSE if it is -a message to be sent to the other peer. - - - - User data passed when adding the filter. - - - - - - Message flags used in #GDBusMessage. - - No flags set. - - - A reply is not expected. - - - The bus must not launch an -owner for the destination name in response to this message. - - - If set on a method -call, this flag means that the caller is prepared to wait for interactive -authorization. Since 2.46. - - - - Header fields used in #GDBusMessage. - - Not a valid header field. - - - The object path. - - - The interface name. - - - The method or signal name. - - - The name of the error that occurred. - - - The serial number the message is a reply to. - - - The name the message is intended for. - - - Unique name of the sender of the message (filled in by the bus). - - - The signature of the message body. - - - The number of UNIX file descriptors that accompany the message. - - - - Message types used in #GDBusMessage. - - Message is of invalid type. - - - Method call. - - - Method reply. - - - Error reply. - - - Signal emission. - - - - Information about a method on an D-Bus interface. - - - The reference count or -1 if statically allocated. - - - - The name of the D-Bus method, e.g. @RequestName. - - - - A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusMethodInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusMethodInfo. - - - - - - - Instances of the #GDBusMethodInvocation class are used when -handling D-Bus method calls. It provides a way to asynchronously -return results and errors. - -The normal way to obtain a #GDBusMethodInvocation object is to receive -it as an argument to the handle_method_call() function in a -#GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). - - Gets the #GDBusConnection the method was invoked on. - - - A #GDBusConnection. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the name of the D-Bus interface the method was invoked on. - -If this method call is a property Get, Set or GetAll call that has -been redirected to the method call handler then -"org.freedesktop.DBus.Properties" will be returned. See -#GDBusInterfaceVTable for more information. - - - A string. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the #GDBusMessage for the method invocation. This is useful if -you need to use low-level protocol features, such as UNIX file -descriptor passing, that cannot be properly expressed in the -#GVariant API. - -See this [server][gdbus-server] and [client][gdbus-unix-fd-client] -for an example of how to use this low-level API to send and receive -UNIX file descriptors. - - - #GDBusMessage. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets information about the method call, if any. - -If this method invocation is a property Get, Set or GetAll call that -has been redirected to the method call handler then %NULL will be -returned. See g_dbus_method_invocation_get_property_info() and -#GDBusInterfaceVTable for more information. - - - A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the name of the method that was invoked. - - - A string. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the object path the method was invoked on. - - - A string. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the parameters of the method invocation. If there are no input -parameters then this will return a GVariant with 0 children rather than NULL. - - - A #GVariant tuple. Do not unref this because it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets information about the property that this method call is for, if -any. - -This will only be set in the case of an invocation in response to a -property Get or Set call that has been directed to the method call -handler for an object on account of its property_get() or -property_set() vtable pointers being unset. - -See #GDBusInterfaceVTable for more information. - -If the call was GetAll, %NULL will be returned. - - - a #GDBusPropertyInfo or %NULL - - - - - A #GDBusMethodInvocation - - - - - - Gets the bus name that invoked the method. - - - A string. Do not free, it is owned by @invocation. - - - - - A #GDBusMethodInvocation. - - - - - - Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). - - - A #gpointer. - - - - - A #GDBusMethodInvocation. - - - - - - Finishes handling a D-Bus method call by returning an error. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A valid D-Bus error name. - - - - A valid D-Bus error message. - - - - - - Finishes handling a D-Bus method call by returning an error. - -See g_dbus_error_encode_gerror() for details about what error name -will be returned on the wire. In a nutshell, if the given error is -registered using g_dbus_error_register_error() the name given -during registration is used. Otherwise, a name of the form -`org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides -transparent mapping of #GError between applications using GDBus. - -If you are writing an application intended to be portable, -always register errors with g_dbus_error_register_error() -or use g_dbus_method_invocation_return_dbus_error(). - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - -Since 2.48, if the method call requested for a reply not to be sent -then this call will free @invocation but otherwise do nothing (as per -the recommendations of the D-Bus specification). - - - - - - - A #GDBusMethodInvocation. - - - - A #GQuark for the #GError error domain. - - - - The error code. - - - - printf()-style format. - - - - Parameters for @format. - - - - - - Like g_dbus_method_invocation_return_error() but without printf()-style formatting. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A #GQuark for the #GError error domain. - - - - The error code. - - - - The error message. - - - - - - Like g_dbus_method_invocation_return_error() but intended for -language bindings. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A #GQuark for the #GError error domain. - - - - The error code. - - - - printf()-style format. - - - - #va_list of parameters for @format. - - - - - - Like g_dbus_method_invocation_return_error() but takes a #GError -instead of the error domain, error code and message. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A #GError. - - - - - - Finishes handling a D-Bus method call by returning @parameters. -If the @parameters GVariant is floating, it is consumed. - -It is an error if @parameters is not of the right format: it must be a tuple -containing the out-parameters of the D-Bus method. Even if the method has a -single out-parameter, it must be contained in a tuple. If the method has no -out-parameters, @parameters may be %NULL or an empty tuple. - -|[<!-- language="C" --> -GDBusMethodInvocation *invocation = some_invocation; -g_autofree gchar *result_string = NULL; -g_autoptr (GError) error = NULL; - -result_string = calculate_result (&error); - -if (error != NULL) - g_dbus_method_invocation_return_gerror (invocation, error); -else - g_dbus_method_invocation_return_value (invocation, - g_variant_new ("(s)", result_string)); - -// Do not free @invocation here; returning a value does that -]| - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - -Since 2.48, if the method call requested for a reply not to be sent -then this call will sink @parameters and free @invocation, but -otherwise do nothing (as per the recommendations of the D-Bus -specification). - - - - - - - A #GDBusMethodInvocation. - - - - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. - - - - - - Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. - -This method is only available on UNIX. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. - - - - A #GUnixFDList or %NULL. - - - - - - Like g_dbus_method_invocation_return_gerror() but takes ownership -of @error so the caller does not need to free it. - -This method will take ownership of @invocation. See -#GDBusInterfaceVTable for more information about the ownership of -@invocation. - - - - - - - A #GDBusMethodInvocation. - - - - A #GError. - - - - - - - Information about nodes in a remote object hierarchy. - - - The reference count or -1 if statically allocated. - - - - The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. - - - - A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - Parses @xml_data and returns a #GDBusNodeInfo representing the data. - -The introspection XML must contain exactly one top-level -<node> element. - -Note that this routine is using a -[GMarkup][glib-Simple-XML-Subset-Parser.description]-based -parser that only accepts a subset of valid XML documents. - - - A #GDBusNodeInfo structure or %NULL if @error is set. Free -with g_dbus_node_info_unref(). - - - - - Valid D-Bus introspection XML. - - - - - - Appends an XML representation of @info (and its children) to @string_builder. - -This function is typically used for generating introspection XML documents at run-time for -handling the `org.freedesktop.DBus.Introspectable.Introspect` method. - - - - - - - A #GDBusNodeInfo. - - - - Indentation level. - - - - A #GString to to append XML data to. - - - - - - Looks up information about an interface. - -The cost of this function is O(n) in number of interfaces. - - - A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. - - - - - A #GDBusNodeInfo. - - - - A D-Bus interface name. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusNodeInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusNodeInfo. - - - - - - - The #GDBusObject type is the base type for D-Bus objects on both -the service side (see #GDBusObjectSkeleton) and the client side -(see #GDBusObjectProxy). It is essentially just a container of -interfaces. - - - Gets the D-Bus interface with name @interface_name associated with -@object, if any. - - - %NULL if not found, otherwise a - #GDBusInterface that must be freed with g_object_unref(). - - - - - A #GDBusObject. - - - - A D-Bus interface name. - - - - - - Gets the D-Bus interfaces associated with @object. - - - A list of #GDBusInterface instances. - The returned list must be freed by g_list_free() after each element has been freed - with g_object_unref(). - - - - - - - A #GDBusObject. - - - - - - Gets the object path for @object. - - - A string owned by @object. Do not free. - - - - - A #GDBusObject. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the D-Bus interface with name @interface_name associated with -@object, if any. - - - %NULL if not found, otherwise a - #GDBusInterface that must be freed with g_object_unref(). - - - - - A #GDBusObject. - - - - A D-Bus interface name. - - - - - - Gets the D-Bus interfaces associated with @object. - - - A list of #GDBusInterface instances. - The returned list must be freed by g_list_free() after each element has been freed - with g_object_unref(). - - - - - - - A #GDBusObject. - - - - - - Gets the object path for @object. - - - A string owned by @object. Do not free. - - - - - A #GDBusObject. - - - - - - Emitted when @interface is added to @object. - - - - - - The #GDBusInterface that was added. - - - - - - Emitted when @interface is removed from @object. - - - - - - The #GDBusInterface that was removed. - - - - - - - Base object type for D-Bus objects. - - - The parent interface. - - - - - - - A string owned by @object. Do not free. - - - - - A #GDBusObject. - - - - - - - - - - A list of #GDBusInterface instances. - The returned list must be freed by g_list_free() after each element has been freed - with g_object_unref(). - - - - - - - A #GDBusObject. - - - - - - - - - - %NULL if not found, otherwise a - #GDBusInterface that must be freed with g_object_unref(). - - - - - A #GDBusObject. - - - - A D-Bus interface name. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GDBusObjectManager type is the base type for service- and -client-side implementations of the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) -interface. - -See #GDBusObjectManagerClient for the client-side implementation -and #GDBusObjectManagerServer for the service-side implementation. - - - Gets the interface proxy for @interface_name at @object_path, if -any. - - - A #GDBusInterface instance or %NULL. Free - with g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - D-Bus interface name to look up. - - - - - - Gets the #GDBusObjectProxy at @object_path, if any. - - - A #GDBusObject or %NULL. Free with - g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - - - Gets the object path that @manager is for. - - - A string owned by @manager. Do not free. - - - - - A #GDBusObjectManager. - - - - - - Gets all #GDBusObject objects known to @manager. - - - A list of - #GDBusObject objects. The returned list should be freed with - g_list_free() after each element has been freed with - g_object_unref(). - - - - - - - A #GDBusObjectManager. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the interface proxy for @interface_name at @object_path, if -any. - - - A #GDBusInterface instance or %NULL. Free - with g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - D-Bus interface name to look up. - - - - - - Gets the #GDBusObjectProxy at @object_path, if any. - - - A #GDBusObject or %NULL. Free with - g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - - - Gets the object path that @manager is for. - - - A string owned by @manager. Do not free. - - - - - A #GDBusObjectManager. - - - - - - Gets all #GDBusObject objects known to @manager. - - - A list of - #GDBusObject objects. The returned list should be freed with - g_list_free() after each element has been freed with - g_object_unref(). - - - - - - - A #GDBusObjectManager. - - - - - - Emitted when @interface is added to @object. - -This signal exists purely as a convenience to avoid having to -connect signals to all objects managed by @manager. - - - - - - The #GDBusObject on which an interface was added. - - - - The #GDBusInterface that was added. - - - - - - Emitted when @interface has been removed from @object. - -This signal exists purely as a convenience to avoid having to -connect signals to all objects managed by @manager. - - - - - - The #GDBusObject on which an interface was removed. - - - - The #GDBusInterface that was removed. - - - - - - Emitted when @object is added to @manager. - - - - - - The #GDBusObject that was added. - - - - - - Emitted when @object is removed from @manager. - - - - - - The #GDBusObject that was removed. - - - - - - - #GDBusObjectManagerClient is used to create, monitor and delete object -proxies for remote objects exported by a #GDBusObjectManagerServer (or any -code implementing the -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) -interface). - -Once an instance of this type has been created, you can connect to -the #GDBusObjectManager::object-added and -#GDBusObjectManager::object-removed signals and inspect the -#GDBusObjectProxy objects returned by -g_dbus_object_manager_get_objects(). - -If the name for a #GDBusObjectManagerClient is not owned by anyone at -object construction time, the default behavior is to request the -message bus to launch an owner for the name. This behavior can be -disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START -flag. It's also worth noting that this only works if the name of -interest is activatable in the first place. E.g. in some cases it -is not possible to launch an owner for the requested name. In this -case, #GDBusObjectManagerClient object construction still succeeds but -there will be no object proxies -(e.g. g_dbus_object_manager_get_objects() returns the empty list) and -the #GDBusObjectManagerClient:name-owner property is %NULL. - -The owner of the requested name can come and go (for example -consider a system service being restarted) – #GDBusObjectManagerClient -handles this case too; simply connect to the #GObject::notify -signal to watch for changes on the #GDBusObjectManagerClient:name-owner -property. When the name owner vanishes, the behavior is that -#GDBusObjectManagerClient:name-owner is set to %NULL (this includes -emission of the #GObject::notify signal) and then -#GDBusObjectManager::object-removed signals are synthesized -for all currently existing object proxies. Since -#GDBusObjectManagerClient:name-owner is %NULL when this happens, you can -use this information to disambiguate a synthesized signal from a -genuine signal caused by object removal on the remote -#GDBusObjectManager. Similarly, when a new name owner appears, -#GDBusObjectManager::object-added signals are synthesized -while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all -object proxies have been added, the #GDBusObjectManagerClient:name-owner -is set to the new name owner (this includes emission of the -#GObject::notify signal). Furthermore, you are guaranteed that -#GDBusObjectManagerClient:name-owner will alternate between a name owner -(e.g. `:1.42`) and %NULL even in the case where -the name of interest is atomically replaced - -Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy -instances. All signals (including the -org.freedesktop.DBus.Properties::PropertiesChanged signal) -delivered to #GDBusProxy instances are guaranteed to originate -from the name owner. This guarantee along with the behavior -described above, means that certain race conditions including the -"half the proxy is from the old owner and the other half is from -the new owner" problem cannot happen. - -To avoid having the application connect to signals on the returned -#GDBusObjectProxy and #GDBusProxy objects, the -#GDBusObject::interface-added, -#GDBusObject::interface-removed, -#GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals -are also emitted on the #GDBusObjectManagerClient instance managing these -objects. The signals emitted are -#GDBusObjectManager::interface-added, -#GDBusObjectManager::interface-removed, -#GDBusObjectManagerClient::interface-proxy-properties-changed and -#GDBusObjectManagerClient::interface-proxy-signal. - -Note that all callbacks and signals are emitted in the -[thread-default main context][g-main-context-push-thread-default] -that the #GDBusObjectManagerClient object was constructed -in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects -originating from the #GDBusObjectManagerClient object will be created in -the same context and, consequently, will deliver signals in the -same main loop. - - - - - - Finishes an operation started with g_dbus_object_manager_client_new(). - - - A - #GDBusObjectManagerClient object or %NULL if @error is set. Free - with g_object_unref(). - - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). - - - - - - Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). - - - A - #GDBusObjectManagerClient object or %NULL if @error is set. Free - with g_object_unref(). - - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). - - - - - - Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead -of a #GDBusConnection. - -This is a synchronous failable constructor - the calling thread is -blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() -for the asynchronous version. - - - A - #GDBusObjectManagerClient object or %NULL if @error is set. Free - with g_object_unref(). - - - - - A #GBusType. - - - - Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - - - - The owner of the control object (unique or well-known name). - - - - The object path of the control object. - - - - A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - - - - User data to pass to @get_proxy_type_func. - - - - Free function for @get_proxy_type_user_data or %NULL. - - - - A #GCancellable or %NULL - - - - - - Creates a new #GDBusObjectManagerClient object. - -This is a synchronous failable constructor - the calling thread is -blocked until a reply is received. See g_dbus_object_manager_client_new() -for the asynchronous version. - - - A - #GDBusObjectManagerClient object or %NULL if @error is set. Free - with g_object_unref(). - - - - - A #GDBusConnection. - - - - Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - - - - The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. - - - - The object path of the control object. - - - - A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - - - - User data to pass to @get_proxy_type_func. - - - - Free function for @get_proxy_type_user_data or %NULL. - - - - A #GCancellable or %NULL - - - - - - Asynchronously creates a new #GDBusObjectManagerClient object. - -This is an asynchronous failable constructor. When the result is -ready, @callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. You can -then call g_dbus_object_manager_client_new_finish() to get the result. See -g_dbus_object_manager_client_new_sync() for the synchronous version. - - - - - - - A #GDBusConnection. - - - - Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - - - - The owner of the control object (unique or well-known name). - - - - The object path of the control object. - - - - A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - - - - User data to pass to @get_proxy_type_func. - - - - Free function for @get_proxy_type_user_data or %NULL. - - - - A #GCancellable or %NULL - - - - A #GAsyncReadyCallback to call when the request is satisfied. - - - - The data to pass to @callback. - - - - - - Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a -#GDBusConnection. - -This is an asynchronous failable constructor. When the result is -ready, @callback will be invoked in the -[thread-default main loop][g-main-context-push-thread-default] -of the thread you are calling this method from. You can -then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See -g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - - - - - - - A #GBusType. - - - - Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - - - - The owner of the control object (unique or well-known name). - - - - The object path of the control object. - - - - A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - - - - User data to pass to @get_proxy_type_func. - - - - Free function for @get_proxy_type_user_data or %NULL. - - - - A #GCancellable or %NULL - - - - A #GAsyncReadyCallback to call when the request is satisfied. - - - - The data to pass to @callback. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the #GDBusConnection used by @manager. - - - A #GDBusConnection object. Do not free, - the object belongs to @manager. - - - - - A #GDBusObjectManagerClient - - - - - - Gets the flags that @manager was constructed with. - - - Zero of more flags from the #GDBusObjectManagerClientFlags -enumeration. - - - - - A #GDBusObjectManagerClient - - - - - - Gets the name that @manager is for, or %NULL if not a message bus -connection. - - - A unique or well-known name. Do not free, the string -belongs to @manager. - - - - - A #GDBusObjectManagerClient - - - - - - The unique name that owns the name that @manager is for or %NULL if -no-one currently owns that name. You can connect to the -#GObject::notify signal to track changes to the -#GDBusObjectManagerClient:name-owner property. - - - The name owner or %NULL if no name owner -exists. Free with g_free(). - - - - - A #GDBusObjectManagerClient. - - - - - - If this property is not %G_BUS_TYPE_NONE, then -#GDBusObjectManagerClient:connection must be %NULL and will be set to the -#GDBusConnection obtained by calling g_bus_get() with the value -of this property. - - - - The #GDBusConnection to use. - - - - Flags from the #GDBusObjectManagerClientFlags enumeration. - - - - A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. - - - - The #GDBusProxyTypeFunc to use when determining what #GType to -use for interface proxies or %NULL. - - - - The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. - - - - The well-known name or unique name that the manager is for. - - - - The unique name that owns #GDBusObjectManagerClient:name or %NULL if -no-one is currently owning the name. Connect to the -#GObject::notify signal to track changes to this property. - - - - The object path the manager is for. - - - - - - - - - - Emitted when one or more D-Bus properties on proxy changes. The -local cache has already been updated when this signal fires. Note -that both @changed_properties and @invalidated_properties are -guaranteed to never be %NULL (either may be empty though). - -This signal exists purely as a convenience to avoid having to -connect signals to all interface proxies managed by @manager. - -This signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] -that @manager was constructed in. - - - - - - The #GDBusObjectProxy on which an interface has properties that are changing. - - - - The #GDBusProxy that has properties that are changing. - - - - A #GVariant containing the properties that changed (type: `a{sv}`). - - - - A %NULL terminated - array of properties that were invalidated. - - - - - - - - Emitted when a D-Bus signal is received on @interface_proxy. - -This signal exists purely as a convenience to avoid having to -connect signals to all interface proxies managed by @manager. - -This signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] -that @manager was constructed in. - - - - - - The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. - - - - The #GDBusProxy that is emitting a D-Bus signal. - - - - The sender of the signal or NULL if the connection is not a bus connection. - - - - The signal name. - - - - A #GVariant tuple with parameters for the signal. - - - - - - - Class structure for #GDBusObjectManagerClient. - - - The parent class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags used when constructing a #GDBusObjectManagerClient. - - No flags set. - - - If not set and the - manager is for a well-known name, then request the bus to launch - an owner for the name if no-one owns the name. This flag can only - be used in managers for well-known names. - - - - - - - Base type for D-Bus object managers. - - - The parent interface. - - - - - - - A string owned by @manager. Do not free. - - - - - A #GDBusObjectManager. - - - - - - - - - - A list of - #GDBusObject objects. The returned list should be freed with - g_list_free() after each element has been freed with - g_object_unref(). - - - - - - - A #GDBusObjectManager. - - - - - - - - - - A #GDBusObject or %NULL. Free with - g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - - - - - - - A #GDBusInterface instance or %NULL. Free - with g_object_unref(). - - - - - A #GDBusObjectManager. - - - - Object path to look up. - - - - D-Bus interface name to look up. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GDBusObjectManagerServer is used to export #GDBusObject instances using -the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) -interface. For example, remote D-Bus clients can get all objects -and properties in a single call. Additionally, any change in the -object hierarchy is broadcast using signals. This means that D-Bus -clients can keep caches up to date by only listening to D-Bus -signals. - -The recommended path to export an object manager at is the path form of the -well-known name of a D-Bus service, or below. For example, if a D-Bus service -is available at the well-known name `net.example.ExampleService1`, the object -manager should typically be exported at `/net/example/ExampleService1`, or -below (to allow for multiple object managers in a service). - -It is supported, but not recommended, to export an object manager at the root -path, `/`. - -See #GDBusObjectManagerClient for the client-side code that is -intended to be used with #GDBusObjectManagerServer or any D-Bus -object implementing the org.freedesktop.DBus.ObjectManager -interface. - - - - Creates a new #GDBusObjectManagerServer object. - -The returned server isn't yet exported on any connection. To do so, -use g_dbus_object_manager_server_set_connection(). Normally you -want to export all of your objects before doing so to avoid -[InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) -signals being emitted. - - - A #GDBusObjectManagerServer object. Free with g_object_unref(). - - - - - The object path to export the manager object at. - - - - - - Exports @object on @manager. - -If there is already a #GDBusObject exported at the object path, -then the old object is removed. - -The object path for @object must be in the hierarchy rooted by the -object path for @manager. - -Note that @manager will take a reference on @object for as long as -it is exported. - - - - - - - A #GDBusObjectManagerServer. - - - - A #GDBusObjectSkeleton. - - - - - - Like g_dbus_object_manager_server_export() but appends a string of -the form _N (with N being a natural number) to @object's object path -if an object with the given path already exists. As such, the -#GDBusObjectProxy:g-object-path property of @object may be modified. - - - - - - - A #GDBusObjectManagerServer. - - - - An object. - - - - - - Gets the #GDBusConnection used by @manager. - - - A #GDBusConnection object or %NULL if - @manager isn't exported on a connection. The returned object should - be freed with g_object_unref(). - - - - - A #GDBusObjectManagerServer - - - - - - Returns whether @object is currently exported on @manager. - - - %TRUE if @object is exported - - - - - A #GDBusObjectManagerServer. - - - - An object. - - - - - - Exports all objects managed by @manager on @connection. If -@connection is %NULL, stops exporting objects. - - - - - - - A #GDBusObjectManagerServer. - - - - A #GDBusConnection or %NULL. - - - - - - If @manager has an object at @path, removes the object. Otherwise -does nothing. - -Note that @object_path must be in the hierarchy rooted by the -object path for @manager. - - - %TRUE if object at @object_path was removed, %FALSE otherwise. - - - - - A #GDBusObjectManagerServer. - - - - An object path. - - - - - - The #GDBusConnection to export objects on. - - - - The object path to register the manager object at. - - - - - - - - - - - Class structure for #GDBusObjectManagerServer. - - - The parent class. - - - - - - - - - - - - - A #GDBusObjectProxy is an object used to represent a remote object -with one or more D-Bus interfaces. Normally, you don't instantiate -a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient -is used to obtain it. - - - - Creates a new #GDBusObjectProxy for the given connection and -object path. - - - a new #GDBusObjectProxy - - - - - a #GDBusConnection - - - - the object path - - - - - - Gets the connection that @proxy is for. - - - A #GDBusConnection. Do not free, the - object is owned by @proxy. - - - - - a #GDBusObjectProxy - - - - - - The connection of the proxy. - - - - The object path of the proxy. - - - - - - - - - - - Class structure for #GDBusObjectProxy. - - - The parent class. - - - - - - - - - - - - - A #GDBusObjectSkeleton instance is essentially a group of D-Bus -interfaces. The set of exported interfaces on the object may be -dynamic and change at runtime. - -This type is intended to be used with #GDBusObjectManager. - - - - Creates a new #GDBusObjectSkeleton. - - - A #GDBusObjectSkeleton. Free with g_object_unref(). - - - - - An object path. - - - - - - - - - - - - - - - - - - - - - - - Adds @interface_ to @object. - -If @object already contains a #GDBusInterfaceSkeleton with the same -interface name, it is removed before @interface_ is added. - -Note that @object takes its own reference on @interface_ and holds -it until removed. - - - - - - - A #GDBusObjectSkeleton. - - - - A #GDBusInterfaceSkeleton. - - - - - - This method simply calls g_dbus_interface_skeleton_flush() on all -interfaces belonging to @object. See that method for when flushing -is useful. - - - - - - - A #GDBusObjectSkeleton. - - - - - - Removes @interface_ from @object. - - - - - - - A #GDBusObjectSkeleton. - - - - A #GDBusInterfaceSkeleton. - - - - - - Removes the #GDBusInterface with @interface_name from @object. - -If no D-Bus interface of the given interface exists, this function -does nothing. - - - - - - - A #GDBusObjectSkeleton. - - - - A D-Bus interface name. - - - - - - Sets the object path for @object. - - - - - - - A #GDBusObjectSkeleton. - - - - A valid D-Bus object path. - - - - - - The object path where the object is exported. - - - - - - - - - - Emitted when a method is invoked by a remote caller and used to -determine if the method call is authorized. - -This signal is like #GDBusInterfaceSkeleton's -#GDBusInterfaceSkeleton::g-authorize-method signal, -except that it is for the enclosing object. - -The default class handler just returns %TRUE. - - %TRUE if the call is authorized, %FALSE otherwise. - - - - - The #GDBusInterfaceSkeleton that @invocation is for. - - - - A #GDBusMethodInvocation. - - - - - - - Class structure for #GDBusObjectSkeleton. - - - The parent class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Information about a D-Bus property on a D-Bus interface. - - - The reference count or -1 if statically allocated. - - - - The name of the D-Bus property, e.g. "SupportedFilesystems". - - - - The D-Bus signature of the property (a single complete type). - - - - Access control flags for the property. - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusPropertyInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusPropertyInfo. - - - - - - - Flags describing the access control of a D-Bus property. - - No flags set. - - - Property is readable. - - - Property is writable. - - - - #GDBusProxy is a base class used for proxies to access a D-Bus -interface on a remote object. A #GDBusProxy can be constructed for -both well-known and unique names. - -By default, #GDBusProxy will cache all properties (and listen to -changes) of the remote object, and proxy all signals that get -emitted. This behaviour can be changed by passing suitable -#GDBusProxyFlags when the proxy is created. If the proxy is for a -well-known name, the property cache is flushed when the name owner -vanishes and reloaded when a name owner appears. - -The unique name owner of the proxy's name is tracked and can be read from -#GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to -get notified of changes. Additionally, only signals and property -changes emitted from the current name owner are considered and -calls are always sent to the current name owner. This avoids a -number of race conditions when the name is lost by one owner and -claimed by another. However, if no name owner currently exists, -then calls will be sent to the well-known name which may result in -the message bus launching an owner (unless -%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). - -The generic #GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals are not very convenient to work with. -Therefore, the recommended way of working with proxies is to subclass -#GDBusProxy, and have more natural properties and signals in your derived -class. This [example][gdbus-example-gdbus-codegen] shows how this can -easily be done using the [gdbus-codegen][gdbus-codegen] tool. - -A #GDBusProxy instance can be used from multiple threads but note -that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed -and #GObject::notify) are emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread where the instance was constructed. - -An example using a proxy for a well-known name can be found in -[gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) - - - - - - Finishes creating a #GDBusProxy. - - - A #GDBusProxy or %NULL if @error is set. - Free with g_object_unref(). - - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). - - - - - - Finishes creating a #GDBusProxy. - - - A #GDBusProxy or %NULL if @error is set. - Free with g_object_unref(). - - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). - - - - - - Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. - -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - - - A #GDBusProxy or %NULL if error is set. - Free with g_object_unref(). - - - - - A #GBusType. - - - - Flags used when constructing the proxy. - - - - A #GDBusInterfaceInfo specifying the minimal interface - that @proxy conforms to or %NULL. - - - - A bus name (well-known or unique). - - - - An object path. - - - - A D-Bus interface name. - - - - A #GCancellable or %NULL. - - - - - - Creates a proxy for accessing @interface_name on the remote object -at @object_path owned by @name at @connection and synchronously -loads D-Bus properties unless the -%G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. - -If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up -match rules for signals. Connect to the #GDBusProxy::g-signal signal -to handle signals from the remote object. - -If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and -%G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is -guaranteed to return immediately without blocking. - -If @name is a well-known name and the -%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION -flags aren't set and no name owner currently exists, the message bus -will be requested to launch a name owner for the name. - -This is a synchronous failable constructor. See g_dbus_proxy_new() -and g_dbus_proxy_new_finish() for the asynchronous version. - -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - - - A #GDBusProxy or %NULL if error is set. - Free with g_object_unref(). - - - - - A #GDBusConnection. - - - - Flags used when constructing the proxy. - - - - A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - - - - A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - - - - An object path. - - - - A D-Bus interface name. - - - - A #GCancellable or %NULL. - - - - - - Creates a proxy for accessing @interface_name on the remote object -at @object_path owned by @name at @connection and asynchronously -loads D-Bus properties unless the -%G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to -the #GDBusProxy::g-properties-changed signal to get notified about -property changes. - -If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up -match rules for signals. Connect to the #GDBusProxy::g-signal signal -to handle signals from the remote object. - -If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and -%G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is -guaranteed to complete immediately without blocking. - -If @name is a well-known name and the -%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION -flags aren't set and no name owner currently exists, the message bus -will be requested to launch a name owner for the name. - -This is a failable asynchronous constructor - when the proxy is -ready, @callback will be invoked and you can use -g_dbus_proxy_new_finish() to get the result. - -See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. - -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - - - - - - - A #GDBusConnection. - - - - Flags used when constructing the proxy. - - - - A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - - - - A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - - - - An object path. - - - - A D-Bus interface name. - - - - A #GCancellable or %NULL. - - - - Callback function to invoke when the proxy is ready. - - - - User data to pass to @callback. - - - - - - Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. - -#GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - - - - - - - A #GBusType. - - - - Flags used when constructing the proxy. - - - - A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - - - - A bus name (well-known or unique). - - - - An object path. - - - - A D-Bus interface name. - - - - A #GCancellable or %NULL. - - - - Callback function to invoke when the proxy is ready. - - - - User data to pass to @callback. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Asynchronously invokes the @method_name method on @proxy. - -If @method_name contains any dots, then @name is split into interface and -method name parts. This allows using @proxy for invoking methods on -other interfaces. - -If the #GDBusConnection associated with @proxy is closed then -the operation will fail with %G_IO_ERROR_CLOSED. If -@cancellable is canceled, the operation will fail with -%G_IO_ERROR_CANCELLED. If @parameters contains a value not -compatible with the D-Bus protocol, the operation fails with -%G_IO_ERROR_INVALID_ARGUMENT. - -If the @parameters #GVariant is floating, it is consumed. This allows -convenient 'inline' use of g_variant_new(), e.g.: -|[<!-- language="C" --> - g_dbus_proxy_call (proxy, - "TwoStrings", - g_variant_new ("(ss)", - "Thing One", - "Thing Two"), - G_DBUS_CALL_FLAGS_NONE, - -1, - NULL, - (GAsyncReadyCallback) two_strings_done, - &data); -]| - -If @proxy has an expected interface (see -#GDBusProxy:g-interface-info) and @method_name is referenced by it, -then the return value is checked against the return type. - -This is an asynchronous method. When the operation is finished, -@callback will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this method from. -You can then call g_dbus_proxy_call_finish() to get the result of -the operation. See g_dbus_proxy_call_sync() for the synchronous -version of this method. - -If @callback is %NULL then the D-Bus method call message will be sent with -the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - - - - - - - A #GDBusProxy. - - - - Name of method to invoke. - - - - A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - - - - Flags from the #GDBusCallFlags enumeration. - - - - The timeout in milliseconds (with %G_MAXINT meaning - "infinite") or -1 to use the proxy default timeout. - - - - A #GCancellable or %NULL. - - - - A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't -care about the result of the method invocation. - - - - The data to pass to @callback. - - - - - - Finishes an operation started with g_dbus_proxy_call(). - - - %NULL if @error is set. Otherwise a #GVariant tuple with -return values. Free with g_variant_unref(). - - - - - A #GDBusProxy. - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). - - - - - - Synchronously invokes the @method_name method on @proxy. - -If @method_name contains any dots, then @name is split into interface and -method name parts. This allows using @proxy for invoking methods on -other interfaces. - -If the #GDBusConnection associated with @proxy is disconnected then -the operation will fail with %G_IO_ERROR_CLOSED. If -@cancellable is canceled, the operation will fail with -%G_IO_ERROR_CANCELLED. If @parameters contains a value not -compatible with the D-Bus protocol, the operation fails with -%G_IO_ERROR_INVALID_ARGUMENT. - -If the @parameters #GVariant is floating, it is consumed. This allows -convenient 'inline' use of g_variant_new(), e.g.: -|[<!-- language="C" --> - g_dbus_proxy_call_sync (proxy, - "TwoStrings", - g_variant_new ("(ss)", - "Thing One", - "Thing Two"), - G_DBUS_CALL_FLAGS_NONE, - -1, - NULL, - &error); -]| - -The calling thread is blocked until a reply is received. See -g_dbus_proxy_call() for the asynchronous version of this -method. - -If @proxy has an expected interface (see -#GDBusProxy:g-interface-info) and @method_name is referenced by it, -then the return value is checked against the return type. - - - %NULL if @error is set. Otherwise a #GVariant tuple with -return values. Free with g_variant_unref(). - - - - - A #GDBusProxy. - - - - Name of method to invoke. - - - - A #GVariant tuple with parameters for the signal - or %NULL if not passing parameters. - - - - Flags from the #GDBusCallFlags enumeration. - - - - The timeout in milliseconds (with %G_MAXINT meaning - "infinite") or -1 to use the proxy default timeout. - - - - A #GCancellable or %NULL. - - - - - - Like g_dbus_proxy_call() but also takes a #GUnixFDList object. - -This method is only available on UNIX. - - - - - - - A #GDBusProxy. - - - - Name of method to invoke. - - - - A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - - - - Flags from the #GDBusCallFlags enumeration. - - - - The timeout in milliseconds (with %G_MAXINT meaning - "infinite") or -1 to use the proxy default timeout. - - - - A #GUnixFDList or %NULL. - - - - A #GCancellable or %NULL. - - - - A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't -care about the result of the method invocation. - - - - The data to pass to @callback. - - - - - - Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). - - - %NULL if @error is set. Otherwise a #GVariant tuple with -return values. Free with g_variant_unref(). - - - - - A #GDBusProxy. - - - - Return location for a #GUnixFDList or %NULL. - - - - A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). - - - - - - Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. - -This method is only available on UNIX. - - - %NULL if @error is set. Otherwise a #GVariant tuple with -return values. Free with g_variant_unref(). - - - - - A #GDBusProxy. - - - - Name of method to invoke. - - - - A #GVariant tuple with parameters for the signal - or %NULL if not passing parameters. - - - - Flags from the #GDBusCallFlags enumeration. - - - - The timeout in milliseconds (with %G_MAXINT meaning - "infinite") or -1 to use the proxy default timeout. - - - - A #GUnixFDList or %NULL. - - - - Return location for a #GUnixFDList or %NULL. - - - - A #GCancellable or %NULL. - - - - - - Looks up the value for a property from the cache. This call does no -blocking IO. - -If @proxy has an expected interface (see -#GDBusProxy:g-interface-info) and @property_name is referenced by -it, then @value is checked against the type of the property. - - - A reference to the #GVariant instance - that holds the value for @property_name or %NULL if the value is not in - the cache. The returned reference must be freed with g_variant_unref(). - - - - - A #GDBusProxy. - - - - Property name. - - - - - - Gets the names of all cached properties on @proxy. - - - A - %NULL-terminated array of strings or %NULL if - @proxy has no cached properties. Free the returned array with - g_strfreev(). - - - - - - - A #GDBusProxy. - - - - - - Gets the connection @proxy is for. - - - A #GDBusConnection owned by @proxy. Do not free. - - - - - A #GDBusProxy. - - - - - - Gets the timeout to use if -1 (specifying default timeout) is -passed as @timeout_msec in the g_dbus_proxy_call() and -g_dbus_proxy_call_sync() functions. - -See the #GDBusProxy:g-default-timeout property for more details. - - - Timeout to use for @proxy. - - - - - A #GDBusProxy. - - - - - - Gets the flags that @proxy was constructed with. - - - Flags from the #GDBusProxyFlags enumeration. - - - - - A #GDBusProxy. - - - - - - Returns the #GDBusInterfaceInfo, if any, specifying the interface -that @proxy conforms to. See the #GDBusProxy:g-interface-info -property for more details. - - - A #GDBusInterfaceInfo or %NULL. - Do not unref the returned object, it is owned by @proxy. - - - - - A #GDBusProxy - - - - - - Gets the D-Bus interface name @proxy is for. - - - A string owned by @proxy. Do not free. - - - - - A #GDBusProxy. - - - - - - Gets the name that @proxy was constructed for. - - - A string owned by @proxy. Do not free. - - - - - A #GDBusProxy. - - - - - - The unique name that owns the name that @proxy is for or %NULL if -no-one currently owns that name. You may connect to the -#GObject::notify signal to track changes to the -#GDBusProxy:g-name-owner property. - - - The name owner or %NULL if no name - owner exists. Free with g_free(). - - - - - A #GDBusProxy. - - - - - - Gets the object path @proxy is for. - - - A string owned by @proxy. Do not free. - - - - - A #GDBusProxy. - - - - - - If @value is not %NULL, sets the cached value for the property with -name @property_name to the value in @value. - -If @value is %NULL, then the cached value is removed from the -property cache. - -If @proxy has an expected interface (see -#GDBusProxy:g-interface-info) and @property_name is referenced by -it, then @value is checked against the type of the property. - -If the @value #GVariant is floating, it is consumed. This allows -convenient 'inline' use of g_variant_new(), e.g. -|[<!-- language="C" --> - g_dbus_proxy_set_cached_property (proxy, - "SomeProperty", - g_variant_new ("(si)", - "A String", - 42)); -]| - -Normally you will not need to use this method since @proxy -is tracking changes using the -`org.freedesktop.DBus.Properties.PropertiesChanged` -D-Bus signal. However, for performance reasons an object may -decide to not use this signal for some properties and instead -use a proprietary out-of-band mechanism to transmit changes. - -As a concrete example, consider an object with a property -`ChatroomParticipants` which is an array of strings. Instead of -transmitting the same (long) array every time the property changes, -it is more efficient to only transmit the delta using e.g. signals -`ChatroomParticipantJoined(String name)` and -`ChatroomParticipantParted(String name)`. - - - - - - - A #GDBusProxy - - - - Property name. - - - - Value for the property or %NULL to remove it from the cache. - - - - - - Sets the timeout to use if -1 (specifying default timeout) is -passed as @timeout_msec in the g_dbus_proxy_call() and -g_dbus_proxy_call_sync() functions. - -See the #GDBusProxy:g-default-timeout property for more details. - - - - - - - A #GDBusProxy. - - - - Timeout in milliseconds. - - - - - - Ensure that interactions with @proxy conform to the given -interface. See the #GDBusProxy:g-interface-info property for more -details. - - - - - - - A #GDBusProxy - - - - Minimum interface this proxy conforms to - or %NULL to unset. - - - - - - If this property is not %G_BUS_TYPE_NONE, then -#GDBusProxy:g-connection must be %NULL and will be set to the -#GDBusConnection obtained by calling g_bus_get() with the value -of this property. - - - - The #GDBusConnection the proxy is for. - - - - The timeout to use if -1 (specifying default timeout) is passed -as @timeout_msec in the g_dbus_proxy_call() and -g_dbus_proxy_call_sync() functions. - -This allows applications to set a proxy-wide timeout for all -remote method invocations on the proxy. If this property is -1, -the default timeout (typically 25 seconds) is used. If set to -%G_MAXINT, then no timeout is used. - - - - Flags from the #GDBusProxyFlags enumeration. - - - - Ensure that interactions with this proxy conform to the given -interface. This is mainly to ensure that malformed data received -from the other peer is ignored. The given #GDBusInterfaceInfo is -said to be the "expected interface". - -The checks performed are: -- When completing a method call, if the type signature of - the reply message isn't what's expected, the reply is - discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - -- Received signals that have a type signature mismatch are dropped and - a warning is logged via g_warning(). - -- Properties received via the initial `GetAll()` call or via the - `::PropertiesChanged` signal (on the - [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) - interface) or set using g_dbus_proxy_set_cached_property() - with a type signature mismatch are ignored and a warning is - logged via g_warning(). - -Note that these checks are never done on methods, signals and -properties that are not referenced in the given -#GDBusInterfaceInfo, since extending a D-Bus interface on the -service-side is not considered an ABI break. - - - - The D-Bus interface name the proxy is for. - - - - The well-known or unique name that the proxy is for. - - - - The unique name that owns #GDBusProxy:g-name or %NULL if no-one -currently owns that name. You may connect to #GObject::notify signal to -track changes to this property. - - - - The object path the proxy is for. - - - - - - - - - - Emitted when one or more D-Bus properties on @proxy changes. The -local cache has already been updated when this signal fires. Note -that both @changed_properties and @invalidated_properties are -guaranteed to never be %NULL (either may be empty though). - -If the proxy has the flag -%G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then -@invalidated_properties will always be empty. - -This signal corresponds to the -`PropertiesChanged` D-Bus signal on the -`org.freedesktop.DBus.Properties` interface. - - - - - - A #GVariant containing the properties that changed (type: `a{sv}`) - - - - A %NULL terminated array of properties that was invalidated - - - - - - - - Emitted when a signal from the remote object and interface that @proxy is for, has been received. - - - - - - The sender of the signal or %NULL if the connection is not a bus connection. - - - - The name of the signal. - - - - A #GVariant tuple with parameters for the signal. - - - - - - - Class structure for #GDBusProxy. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags used when constructing an instance of a #GDBusProxy derived class. - - No flags set. - - - Don't load properties. - - - Don't connect to signals on the remote object. - - - If the proxy is for a well-known name, -do not ask the bus to launch an owner during proxy initialization or a method call. -This flag is only meaningful in proxies for well-known names. - - - If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. - - - If the proxy is for a well-known name, -do not ask the bus to launch an owner during proxy initialization, but allow it to be -autostarted by a method call. This flag is only meaningful in proxies for well-known names, -and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. - - - - - - - Function signature for a function used to determine the #GType to -use for an interface proxy (if @interface_name is not %NULL) or -object proxy (if @interface_name is %NULL). - -This function is called in the -[thread-default main loop][g-main-context-push-thread-default] -that @manager was constructed in. - - - A #GType to use for the remote object. The returned type - must be a #GDBusProxy or #GDBusObjectProxy -derived - type. - - - - - A #GDBusObjectManagerClient. - - - - The object path of the remote object. - - - - The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested. - - - - User data. - - - - - - Flags used when sending #GDBusMessages on a #GDBusConnection. - - No flags set. - - - Do not automatically -assign a serial number from the #GDBusConnection object when -sending a message. - - - - #GDBusServer is a helper for listening to and accepting D-Bus -connections. This can be used to create a new D-Bus server, allowing two -peers to use the D-Bus protocol for their own specialized communication. -A server instance provided in this way will not perform message routing or -implement the org.freedesktop.DBus interface. - -To just export an object on a well-known name on a message bus, such as the -session or system bus, you should instead use g_bus_own_name(). - -An example of peer-to-peer communication with G-DBus can be found -in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). - -Note that a minimal #GDBusServer will accept connections from any -peer. In many use-cases it will be necessary to add a #GDBusAuthObserver -that only accepts connections that have successfully authenticated -as the same user that is running the #GDBusServer. - - - Creates a new D-Bus server that listens on the first address in -@address that works. - -Once constructed, you can use g_dbus_server_get_client_address() to -get a D-Bus address string that clients can use to connect. - -To have control over the available authentication mechanisms and -the users that are authorized to connect, it is strongly recommended -to provide a non-%NULL #GDBusAuthObserver. - -Connect to the #GDBusServer::new-connection signal to handle -incoming connections. - -The returned #GDBusServer isn't active - you have to start it with -g_dbus_server_start(). - -#GDBusServer is used in this [example][gdbus-peer-to-peer]. - -This is a synchronous failable constructor. There is currently no -asynchronous version. - - - A #GDBusServer or %NULL if @error is set. Free with -g_object_unref(). - - - - - A D-Bus address. - - - - Flags from the #GDBusServerFlags enumeration. - - - - A D-Bus GUID. - - - - A #GDBusAuthObserver or %NULL. - - - - A #GCancellable or %NULL. - - - - - - Gets a -[D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) -string that can be used by clients to connect to @server. - - - A D-Bus address string. Do not free, the string is owned -by @server. - - - - - A #GDBusServer. - - - - - - Gets the flags for @server. - - - A set of flags from the #GDBusServerFlags enumeration. - - - - - A #GDBusServer. - - - - - - Gets the GUID for @server. - - - A D-Bus GUID. Do not free this string, it is owned by @server. - - - - - A #GDBusServer. - - - - - - Gets whether @server is active. - - - %TRUE if server is active, %FALSE otherwise. - - - - - A #GDBusServer. - - - - - - Starts @server. - - - - - - - A #GDBusServer. - - - - - - Stops @server. - - - - - - - A #GDBusServer. - - - - - - Whether the server is currently active. - - - - The D-Bus address to listen on. - - - - A #GDBusAuthObserver object to assist in the authentication process or %NULL. - - - - The D-Bus address that clients can use. - - - - Flags from the #GDBusServerFlags enumeration. - - - - The guid of the server. - - - - Emitted when a new authenticated connection has been made. Use -g_dbus_connection_get_peer_credentials() to figure out what -identity (if any), was authenticated. - -If you want to accept the connection, take a reference to the -@connection object and return %TRUE. When you are done with the -connection call g_dbus_connection_close() and give up your -reference. Note that the other peer may disconnect at any time - -a typical thing to do when accepting a connection is to listen to -the #GDBusConnection::closed signal. - -If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD -then the signal is emitted in a new thread dedicated to the -connection. Otherwise the signal is emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that @server was constructed in. - -You are guaranteed that signal handlers for this signal runs -before incoming messages on @connection are processed. This means -that it's suitable to call g_dbus_connection_register_object() or -similar from the signal handler. - - %TRUE to claim @connection, %FALSE to let other handlers -run. - - - - - A #GDBusConnection for the new connection. - - - - - - - Flags used when creating a #GDBusServer. - - No flags set. - - - All #GDBusServer::new-connection -signals will run in separated dedicated threads (see signal for -details). - - - Allow the anonymous -authentication method. - - - - Signature for callback function used in g_dbus_connection_signal_subscribe(). - - - - - - - A #GDBusConnection. - - - - The unique bus name of the sender of the signal. - - - - The object path that the signal was emitted on. - - - - The name of the interface. - - - - The name of the signal. - - - - A #GVariant tuple with parameters for the signal. - - - - User data passed when subscribing to the signal. - - - - - - Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). - - No flags set. - - - Don't actually send the AddMatch -D-Bus call for this signal subscription. This gives you more control -over which match rules you add (but you must add them manually). - - - Match first arguments that -contain a bus or interface name with the given namespace. - - - Match first arguments that -contain an object path that is either equivalent to the given path, -or one of the paths is a subpath of the other. - - - - Information about a signal on a D-Bus interface. - - - The reference count or -1 if statically allocated. - - - - The name of the D-Bus signal, e.g. "NameOwnerChanged". - - - - A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments. - - - - - - A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - - - - - - If @info is statically allocated does nothing. Otherwise increases -the reference count. - - - The same @info. - - - - - A #GDBusSignalInfo - - - - - - If @info is statically allocated, does nothing. Otherwise decreases -the reference count of @info. When its reference count drops to 0, -the memory used is freed. - - - - - - - A #GDBusSignalInfo. - - - - - - - The type of the @dispatch function in #GDBusSubtreeVTable. - -Subtrees are flat. @node, if non-%NULL, is always exactly one -segment of the object path (ie: it never contains a slash). - - - A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that was registered with g_dbus_connection_register_subtree(). - - - - The D-Bus interface name that the method call or property access is for. - - - - A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. - - - - Return location for user data to pass to functions in the returned #GDBusInterfaceVTable. - - - - The @user_data #gpointer passed to g_dbus_connection_register_subtree(). - - - - - - The type of the @enumerate function in #GDBusSubtreeVTable. - -This function is called when generating introspection data and also -when preparing to dispatch incoming messages in the event that the -%G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not -specified (ie: to verify that the object path is valid). - -Hierarchies are not supported; the items that you return should not -contain the '/' character. - -The return value will be freed with g_strfreev(). - - - A newly allocated array of strings for node names that are children of @object_path. - - - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that was registered with g_dbus_connection_register_subtree(). - - - - The @user_data #gpointer passed to g_dbus_connection_register_subtree(). - - - - - - Flags passed to g_dbus_connection_register_subtree(). - - No flags set. - - - Method calls to objects not in the enumerated range - will still be dispatched. This is useful if you want - to dynamically spawn objects in the subtree. - - - - The type of the @introspect function in #GDBusSubtreeVTable. - -Subtrees are flat. @node, if non-%NULL, is always exactly one -segment of the object path (ie: it never contains a slash). - -This function should return %NULL to indicate that there is no object -at this node. - -If this function returns non-%NULL, the return value is expected to -be a %NULL-terminated array of pointers to #GDBusInterfaceInfo -structures describing the interfaces implemented by @node. This -array will have g_dbus_interface_info_unref() called on each item -before being freed with g_free(). - -The difference between returning %NULL and an array containing zero -items is that the standard DBus interfaces will returned to the -remote introspector in the empty array case, but not in the %NULL -case. - - - A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. - - - - - A #GDBusConnection. - - - - The unique bus name of the remote caller. - - - - The object path that was registered with g_dbus_connection_register_subtree(). - - - - A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. - - - - The @user_data #gpointer passed to g_dbus_connection_register_subtree(). - - - - - - Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). - - - Function for enumerating child nodes. - - - - Function for introspecting a child node. - - - - Function for dispatching a remote call on a child node. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for default handler to URI association. See -[Extending GIO][extending-gio]. - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - - - - - - - - - - - - - - - - - - - - - - - - - - The string used to obtain a Unix device path with g_drive_get_identifier(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Data input stream implements #GInputStream and includes functions for -reading structured data directly from a binary input stream. - - - - Creates a new data input stream for the @base_stream. - - - a new #GDataInputStream. - - - - - a #GInputStream. - - - - - - Gets the byte order for the data input stream. - - - the @stream's current #GDataStreamByteOrder. - - - - - a given #GDataInputStream. - - - - - - Gets the current newline type for the @stream. - - - #GDataStreamNewlineType for the given @stream. - - - - - a given #GDataInputStream. - - - - - - Reads an unsigned 8-bit/1-byte value from @stream. - - - an unsigned 8-bit/1-byte value read from the @stream or `0` -if an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads a 16-bit/2-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - - - a signed 16-bit/2-byte value read from @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads a signed 32-bit/4-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a signed 32-bit/4-byte value read from the @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads a 64-bit/8-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a signed 64-bit/8-byte value read from @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads a line from the data input stream. Note that no encoding -checks or conversion is performed; the input is not guaranteed to -be UTF-8, and may in fact have embedded NUL characters. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - a NUL terminated byte array with the line that was read in - (without the newlines). Set @length to a #gsize to get the length - of the read line. On an error, it will return %NULL and @error - will be set. If there's no content to read, it will still return - %NULL, but @error won't be set. - - - - - - - a given #GDataInputStream. - - - - a #gsize to get the length of the data read in. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - The asynchronous version of g_data_input_stream_read_line(). It is -an error to have two outstanding calls to this function. - -When the operation is finished, @callback will be called. You -can then call g_data_input_stream_read_line_finish() to get -the result of the operation. - - - - - - - a given #GDataInputStream. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied. - - - - the data to pass to callback function. - - - - - - Finish an asynchronous call started by -g_data_input_stream_read_line_async(). Note the warning about -string encoding in g_data_input_stream_read_line() applies here as -well. - - - - a NUL-terminated byte array with the line that was read in - (without the newlines). Set @length to a #gsize to get the length - of the read line. On an error, it will return %NULL and @error - will be set. If there's no content to read, it will still return - %NULL, but @error won't be set. - - - - - - - a given #GDataInputStream. - - - - the #GAsyncResult that was provided to the callback. - - - - a #gsize to get the length of the data read in. - - - - - - Finish an asynchronous call started by -g_data_input_stream_read_line_async(). - - - a string with the line that - was read in (without the newlines). Set @length to a #gsize to - get the length of the read line. On an error, it will return - %NULL and @error will be set. For UTF-8 conversion errors, the set - error domain is %G_CONVERT_ERROR. If there's no content to read, - it will still return %NULL, but @error won't be set. - - - - - a given #GDataInputStream. - - - - the #GAsyncResult that was provided to the callback. - - - - a #gsize to get the length of the data read in. - - - - - - Reads a UTF-8 encoded line from the data input stream. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a NUL terminated UTF-8 string - with the line that was read in (without the newlines). Set - @length to a #gsize to get the length of the read line. On an - error, it will return %NULL and @error will be set. For UTF-8 - conversion errors, the set error domain is %G_CONVERT_ERROR. If - there's no content to read, it will still return %NULL, but @error - won't be set. - - - - - a given #GDataInputStream. - - - - a #gsize to get the length of the data read in. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads an unsigned 16-bit/2-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - - - an unsigned 16-bit/2-byte value read from the @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads an unsigned 32-bit/4-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - an unsigned 32-bit/4-byte value read from the @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads an unsigned 64-bit/8-byte value from @stream. - -In order to get the correct byte order for this read operation, -see g_data_input_stream_get_byte_order(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - an unsigned 64-bit/8-byte read from @stream or `0` if -an error occurred. - - - - - a given #GDataInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Reads a string from the data input stream, up to the first -occurrence of any of the stop characters. - -Note that, in contrast to g_data_input_stream_read_until_async(), -this function consumes the stop character that it finds. - -Don't use this function in new code. Its functionality is -inconsistent with g_data_input_stream_read_until_async(). Both -functions will be marked as deprecated in a future release. Use -g_data_input_stream_read_upto() instead, but note that that function -does not consume the stop character. - Use g_data_input_stream_read_upto() instead, which has more - consistent behaviour regarding the stop character. - - - a string with the data that was read - before encountering any of the stop characters. Set @length to - a #gsize to get the length of the string. This function will - return %NULL on an error. - - - - - a given #GDataInputStream. - - - - characters to terminate the read. - - - - a #gsize to get the length of the data read in. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - The asynchronous version of g_data_input_stream_read_until(). -It is an error to have two outstanding calls to this function. - -Note that, in contrast to g_data_input_stream_read_until(), -this function does not consume the stop character that it finds. You -must read it for yourself. - -When the operation is finished, @callback will be called. You -can then call g_data_input_stream_read_until_finish() to get -the result of the operation. - -Don't use this function in new code. Its functionality is -inconsistent with g_data_input_stream_read_until(). Both functions -will be marked as deprecated in a future release. Use -g_data_input_stream_read_upto_async() instead. - Use g_data_input_stream_read_upto_async() instead, which - has more consistent behaviour regarding the stop character. - - - - - - - a given #GDataInputStream. - - - - characters to terminate the read. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied. - - - - the data to pass to callback function. - - - - - - Finish an asynchronous call started by -g_data_input_stream_read_until_async(). - Use g_data_input_stream_read_upto_finish() instead, which - has more consistent behaviour regarding the stop character. - - - a string with the data that was read - before encountering any of the stop characters. Set @length to - a #gsize to get the length of the string. This function will - return %NULL on an error. - - - - - a given #GDataInputStream. - - - - the #GAsyncResult that was provided to the callback. - - - - a #gsize to get the length of the data read in. - - - - - - Reads a string from the data input stream, up to the first -occurrence of any of the stop characters. - -In contrast to g_data_input_stream_read_until(), this function -does not consume the stop character. You have to use -g_data_input_stream_read_byte() to get it before calling -g_data_input_stream_read_upto() again. - -Note that @stop_chars may contain '\0' if @stop_chars_len is -specified. - -The returned string will always be nul-terminated on success. - - - a string with the data that was read - before encountering any of the stop characters. Set @length to - a #gsize to get the length of the string. This function will - return %NULL on an error - - - - - a #GDataInputStream - - - - characters to terminate the read - - - - length of @stop_chars. May be -1 if @stop_chars is - nul-terminated - - - - a #gsize to get the length of the data read in - - - - optional #GCancellable object, %NULL to ignore - - - - - - The asynchronous version of g_data_input_stream_read_upto(). -It is an error to have two outstanding calls to this function. - -In contrast to g_data_input_stream_read_until(), this function -does not consume the stop character. You have to use -g_data_input_stream_read_byte() to get it before calling -g_data_input_stream_read_upto() again. - -Note that @stop_chars may contain '\0' if @stop_chars_len is -specified. - -When the operation is finished, @callback will be called. You -can then call g_data_input_stream_read_upto_finish() to get -the result of the operation. - - - - - - - a #GDataInputStream - - - - characters to terminate the read - - - - length of @stop_chars. May be -1 if @stop_chars is - nul-terminated - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finish an asynchronous call started by -g_data_input_stream_read_upto_async(). - -Note that this function does not consume the stop character. You -have to use g_data_input_stream_read_byte() to get it before calling -g_data_input_stream_read_upto_async() again. - -The returned string will always be nul-terminated on success. - - - a string with the data that was read - before encountering any of the stop characters. Set @length to - a #gsize to get the length of the string. This function will - return %NULL on an error. - - - - - a #GDataInputStream - - - - the #GAsyncResult that was provided to the callback - - - - a #gsize to get the length of the data read in - - - - - - This function sets the byte order for the given @stream. All subsequent -reads from the @stream will be read in the given @order. - - - - - - - a given #GDataInputStream. - - - - a #GDataStreamByteOrder to set. - - - - - - Sets the newline type for the @stream. - -Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read -chunk ends in "CR" we must read an additional byte to know if this is "CR" or -"CR LF", and this might block if there is no more data available. - - - - - - - a #GDataInputStream. - - - - the type of new line return as #GDataStreamNewlineType. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Data output stream implements #GOutputStream and includes functions for -writing data directly to an output stream. - - - - Creates a new data output stream for @base_stream. - - - #GDataOutputStream. - - - - - a #GOutputStream. - - - - - - Gets the byte order for the stream. - - - the #GDataStreamByteOrder for the @stream. - - - - - a #GDataOutputStream. - - - - - - Puts a byte into the output stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #guchar. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts a signed 16-bit integer into the output stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #gint16. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts a signed 32-bit integer into the output stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #gint32. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts a signed 64-bit integer into the stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #gint64. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts a string into the output stream. - - - %TRUE if @string was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts an unsigned 16-bit integer into the output stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #guint16. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts an unsigned 32-bit integer into the stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #guint32. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Puts an unsigned 64-bit integer into the stream. - - - %TRUE if @data was successfully added to the @stream. - - - - - a #GDataOutputStream. - - - - a #guint64. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Sets the byte order of the data output stream to @order. - - - - - - - a #GDataOutputStream. - - - - a %GDataStreamByteOrder. - - - - - - Determines the byte ordering that is used when writing -multi-byte entities (such as integers) to the stream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources -across various machine architectures. - - Selects Big Endian byte order. - - - Selects Little Endian byte order. - - - Selects endianness based on host machine's architecture. - - - - #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. - - Selects "LF" line endings, common on most modern UNIX platforms. - - - Selects "CR" line endings. - - - Selects "CR, LF" line ending, common on Microsoft Windows. - - - Automatically try to handle any line ending type. - - - - A #GDatagramBased is a networking interface for representing datagram-based -communications. It is a more or less direct mapping of the core parts of the -BSD socket API in a portable GObject interface. It is implemented by -#GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. - -#GDatagramBased is entirely platform independent, and is intended to be used -alongside higher-level networking APIs such as #GIOStream. - -It uses vectored scatter/gather I/O by default, allowing for many messages -to be sent or received in a single call. Where possible, implementations of -the interface should take advantage of vectored I/O to minimise processing -or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where -possible. Callers should take advantage of scatter/gather I/O (the use of -multiple buffers per message) to avoid unnecessary copying of data to -assemble or disassemble a message. - -Each #GDatagramBased operation has a timeout parameter which may be negative -for blocking behaviour, zero for non-blocking behaviour, or positive for -timeout behaviour. A blocking operation blocks until finished or there is an -error. A non-blocking operation will return immediately with a -%G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation -will block until the operation is complete or the timeout expires; if the -timeout expires it will return what progress it made, or -%G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would -successfully run you can call g_datagram_based_condition_check() or -g_datagram_based_condition_wait(). You can also use -g_datagram_based_create_source() and attach it to a #GMainContext to get -callbacks when I/O is possible. - -When running a non-blocking operation applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function -said that I/O was possible. This can easily happen in case of a race -condition in the application, but it can also happen for other reasons. For -instance, on Windows a socket is always seen as writable until a write -returns %G_IO_ERROR_WOULD_BLOCK. - -As with #GSocket, #GDatagramBaseds can be either connection oriented (for -example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be -datagram-based, not stream-based. The interface does not cover connection -establishment — use methods on the underlying type to establish a connection -before sending and receiving data through the #GDatagramBased API. For -connectionless socket types the target/source address is specified or -received in each I/O operation. - -Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. -To use a #GDatagramBased concurrently from multiple threads, you must -implement your own locking. - - - Checks on the readiness of @datagram_based to perform operations. The -operations specified in @condition are checked for and masked against the -currently-satisfied conditions on @datagram_based. The result is returned. - -%G_IO_IN will be set in the return value if data is available to read with -g_datagram_based_receive_messages(), or if the connection is closed remotely -(EOS); and if the datagram_based has not been closed locally using some -implementation-specific method (such as g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -%G_IO_OUT will be set if it is expected that at least one byte can be sent -using g_datagram_based_send_messages() without blocking. It will not be set -if the datagram_based has been closed locally. - -%G_IO_HUP will be set if the connection has been closed locally. - -%G_IO_ERR will be set if there was an asynchronous error in transmitting data -previously enqueued using g_datagram_based_send_messages(). - -Note that on Windows, it is possible for an operation to return -%G_IO_ERROR_WOULD_BLOCK even immediately after -g_datagram_based_condition_check() has claimed that the #GDatagramBased is -ready for writing. Rather than calling g_datagram_based_condition_check() and -then writing to the #GDatagramBased if it succeeds, it is generally better to -simply try writing right away, and try again later if the initial attempt -returns %G_IO_ERROR_WOULD_BLOCK. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these -conditions will always be set in the output if they are true. Apart from -these flags, the output is guaranteed to be masked by @condition. - -This call never blocks. - - - the #GIOCondition mask of the current state - - - - - a #GDatagramBased - - - - a #GIOCondition mask to check - - - - - - Waits for up to @timeout microseconds for condition to become true on -@datagram_based. If the condition is met, %TRUE is returned. - -If @cancellable is cancelled before the condition is met, or if @timeout is -reached before the condition is met, then %FALSE is returned and @error is -set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). - - - %TRUE if the condition was met, %FALSE otherwise - - - - - a #GDatagramBased - - - - a #GIOCondition mask to wait for - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a #GCancellable - - - - - - Creates a #GSource that can be attached to a #GMainContext to monitor for -the availability of the specified @condition on the #GDatagramBased. The -#GSource keeps a reference to the @datagram_based. - -The callback on the source is of the #GDatagramBasedSourceFunc type. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these -conditions will always be reported in the callback if they are true. - -If non-%NULL, @cancellable can be used to cancel the source, which will -cause the source to trigger, reporting the current condition (which is -likely 0 unless cancellation happened at the same time as a condition -change). You can check for this in the callback using -g_cancellable_is_cancelled(). - - - a newly allocated #GSource - - - - - a #GDatagramBased - - - - a #GIOCondition mask to monitor - - - - a #GCancellable - - - - - - Receive one or more data messages from @datagram_based in one go. - -@messages must point to an array of #GInputMessage structs and -@num_messages must be the length of this array. Each #GInputMessage -contains a pointer to an array of #GInputVector structs describing the -buffers that the data received in each message will be written to. - -@flags modify how all messages are received. The commonly available -arguments for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. These -flags affect the overall receive operation. Flags affecting individual -messages are returned in #GInputMessage.flags. - -The other members of #GInputMessage are treated as described in its -documentation. - -If @timeout is negative the call will block until @num_messages have been -received, the connection is closed remotely (EOS), @cancellable is cancelled, -or an error occurs. - -If @timeout is 0 the call will return up to @num_messages without blocking, -or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system -to be received. - -If @timeout is positive the call will block on the same conditions as if -@timeout were negative. If the timeout is reached -before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, -otherwise it will return the number of messages received before timing out. -(Note: This is effectively the behaviour of `MSG_WAITFORONE` with -recvmmsg().) - -To be notified when messages are available, wait for the %G_IO_IN condition. -Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from -g_datagram_based_receive_messages() even if you were previously notified of a -%G_IO_IN condition. - -If the remote peer closes the connection, any messages queued in the -underlying receive buffer will be returned, and subsequent calls to -g_datagram_based_receive_messages() will return 0 (with no error set). - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be received; otherwise the number of -messages successfully received before the error will be returned. If -@cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any -other error. - - - number of messages received, or -1 on error. Note that the number - of messages received may be smaller than @num_messages if @timeout is - zero or positive, if the peer closed the connection, or if @num_messages - was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - to receive the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GInputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags for the overall operation - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - Send one or more data messages from @datagram_based in one go. - -@messages must point to an array of #GOutputMessage structs and -@num_messages must be the length of this array. Each #GOutputMessage -contains an address to send the data to, and a pointer to an array of -#GOutputVector structs to describe the buffers that the data to be sent -for each message will be gathered from. - -@flags modify how the message is sent. The commonly available arguments -for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. - -The other members of #GOutputMessage are treated as described in its -documentation. - -If @timeout is negative the call will block until @num_messages have been -sent, @cancellable is cancelled, or an error occurs. - -If @timeout is 0 the call will send up to @num_messages without blocking, -or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. - -If @timeout is positive the call will block on the same conditions as if -@timeout were negative. If the timeout is reached before any messages are -sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number -of messages sent before timing out. - -To be notified when messages can be sent, wait for the %G_IO_OUT condition. -Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from -g_datagram_based_send_messages() even if you were previously notified of a -%G_IO_OUT condition. (On Windows in particular, this is very common due to -the way the underlying APIs work.) - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be sent; otherwise the number of messages -successfully sent before the error will be returned. If @cancellable is -cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - - - number of messages sent, or -1 on error. Note that the number of - messages sent may be smaller than @num_messages if @timeout is zero - or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in - which case the caller may re-try to send the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GOutputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - Checks on the readiness of @datagram_based to perform operations. The -operations specified in @condition are checked for and masked against the -currently-satisfied conditions on @datagram_based. The result is returned. - -%G_IO_IN will be set in the return value if data is available to read with -g_datagram_based_receive_messages(), or if the connection is closed remotely -(EOS); and if the datagram_based has not been closed locally using some -implementation-specific method (such as g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -%G_IO_OUT will be set if it is expected that at least one byte can be sent -using g_datagram_based_send_messages() without blocking. It will not be set -if the datagram_based has been closed locally. - -%G_IO_HUP will be set if the connection has been closed locally. - -%G_IO_ERR will be set if there was an asynchronous error in transmitting data -previously enqueued using g_datagram_based_send_messages(). - -Note that on Windows, it is possible for an operation to return -%G_IO_ERROR_WOULD_BLOCK even immediately after -g_datagram_based_condition_check() has claimed that the #GDatagramBased is -ready for writing. Rather than calling g_datagram_based_condition_check() and -then writing to the #GDatagramBased if it succeeds, it is generally better to -simply try writing right away, and try again later if the initial attempt -returns %G_IO_ERROR_WOULD_BLOCK. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these -conditions will always be set in the output if they are true. Apart from -these flags, the output is guaranteed to be masked by @condition. - -This call never blocks. - - - the #GIOCondition mask of the current state - - - - - a #GDatagramBased - - - - a #GIOCondition mask to check - - - - - - Waits for up to @timeout microseconds for condition to become true on -@datagram_based. If the condition is met, %TRUE is returned. - -If @cancellable is cancelled before the condition is met, or if @timeout is -reached before the condition is met, then %FALSE is returned and @error is -set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). - - - %TRUE if the condition was met, %FALSE otherwise - - - - - a #GDatagramBased - - - - a #GIOCondition mask to wait for - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a #GCancellable - - - - - - Creates a #GSource that can be attached to a #GMainContext to monitor for -the availability of the specified @condition on the #GDatagramBased. The -#GSource keeps a reference to the @datagram_based. - -The callback on the source is of the #GDatagramBasedSourceFunc type. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these -conditions will always be reported in the callback if they are true. - -If non-%NULL, @cancellable can be used to cancel the source, which will -cause the source to trigger, reporting the current condition (which is -likely 0 unless cancellation happened at the same time as a condition -change). You can check for this in the callback using -g_cancellable_is_cancelled(). - - - a newly allocated #GSource - - - - - a #GDatagramBased - - - - a #GIOCondition mask to monitor - - - - a #GCancellable - - - - - - Receive one or more data messages from @datagram_based in one go. - -@messages must point to an array of #GInputMessage structs and -@num_messages must be the length of this array. Each #GInputMessage -contains a pointer to an array of #GInputVector structs describing the -buffers that the data received in each message will be written to. - -@flags modify how all messages are received. The commonly available -arguments for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. These -flags affect the overall receive operation. Flags affecting individual -messages are returned in #GInputMessage.flags. - -The other members of #GInputMessage are treated as described in its -documentation. - -If @timeout is negative the call will block until @num_messages have been -received, the connection is closed remotely (EOS), @cancellable is cancelled, -or an error occurs. - -If @timeout is 0 the call will return up to @num_messages without blocking, -or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system -to be received. - -If @timeout is positive the call will block on the same conditions as if -@timeout were negative. If the timeout is reached -before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, -otherwise it will return the number of messages received before timing out. -(Note: This is effectively the behaviour of `MSG_WAITFORONE` with -recvmmsg().) - -To be notified when messages are available, wait for the %G_IO_IN condition. -Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from -g_datagram_based_receive_messages() even if you were previously notified of a -%G_IO_IN condition. - -If the remote peer closes the connection, any messages queued in the -underlying receive buffer will be returned, and subsequent calls to -g_datagram_based_receive_messages() will return 0 (with no error set). - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be received; otherwise the number of -messages successfully received before the error will be returned. If -@cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any -other error. - - - number of messages received, or -1 on error. Note that the number - of messages received may be smaller than @num_messages if @timeout is - zero or positive, if the peer closed the connection, or if @num_messages - was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - to receive the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GInputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags for the overall operation - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - Send one or more data messages from @datagram_based in one go. - -@messages must point to an array of #GOutputMessage structs and -@num_messages must be the length of this array. Each #GOutputMessage -contains an address to send the data to, and a pointer to an array of -#GOutputVector structs to describe the buffers that the data to be sent -for each message will be gathered from. - -@flags modify how the message is sent. The commonly available arguments -for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. - -The other members of #GOutputMessage are treated as described in its -documentation. - -If @timeout is negative the call will block until @num_messages have been -sent, @cancellable is cancelled, or an error occurs. - -If @timeout is 0 the call will send up to @num_messages without blocking, -or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. - -If @timeout is positive the call will block on the same conditions as if -@timeout were negative. If the timeout is reached before any messages are -sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number -of messages sent before timing out. - -To be notified when messages can be sent, wait for the %G_IO_OUT condition. -Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from -g_datagram_based_send_messages() even if you were previously notified of a -%G_IO_OUT condition. (On Windows in particular, this is very common due to -the way the underlying APIs work.) - -If the connection is shut down or closed (by calling g_socket_close() or -g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for -example), all calls to this function will return %G_IO_ERROR_CLOSED. - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be sent; otherwise the number of messages -successfully sent before the error will be returned. If @cancellable is -cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - - - number of messages sent, or -1 on error. Note that the number of - messages sent may be smaller than @num_messages if @timeout is zero - or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in - which case the caller may re-try to send the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GOutputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - - Provides an interface for socket-like objects which have datagram semantics, -following the Berkeley sockets API. The interface methods are thin wrappers -around the corresponding virtual methods, and no pre-processing of inputs is -implemented — so implementations of this API must handle all functionality -documented in the interface methods. - - - The parent interface. - - - - - - - number of messages received, or -1 on error. Note that the number - of messages received may be smaller than @num_messages if @timeout is - zero or positive, if the peer closed the connection, or if @num_messages - was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - to receive the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GInputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags for the overall operation - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - - - - - number of messages sent, or -1 on error. Note that the number of - messages sent may be smaller than @num_messages if @timeout is zero - or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in - which case the caller may re-try to send the remaining messages. - - - - - a #GDatagramBased - - - - an array of #GOutputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a %GCancellable - - - - - - - - - - a newly allocated #GSource - - - - - a #GDatagramBased - - - - a #GIOCondition mask to monitor - - - - a #GCancellable - - - - - - - - - - the #GIOCondition mask of the current state - - - - - a #GDatagramBased - - - - a #GIOCondition mask to check - - - - - - - - - - %TRUE if the condition was met, %FALSE otherwise - - - - - a #GDatagramBased - - - - a #GIOCondition mask to wait for - - - - the maximum time (in microseconds) to wait, 0 to not block, or -1 - to block indefinitely - - - - a #GCancellable - - - - - - - - This is the function type of the callback used for the #GSource -returned by g_datagram_based_create_source(). - - - %G_SOURCE_REMOVE if the source should be removed, - %G_SOURCE_CONTINUE otherwise - - - - - the #GDatagramBased - - - - the current condition at the source fired - - - - data passed in by the user - - - - - - #GDesktopAppInfo is an implementation of #GAppInfo based on -desktop files. - -Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific -GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - - Creates a new #GDesktopAppInfo based on a desktop file id. - -A desktop file id is the basename of the desktop file, including the -.desktop extension. GIO is looking for a desktop file with this name -in the `applications` subdirectories of the XDG -data directories (i.e. the directories specified in the `XDG_DATA_HOME` -and `XDG_DATA_DIRS` environment variables). GIO also supports the -prefix-to-subdirectory mapping that is described in the -[Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) -(i.e. a desktop id of kde-foo.desktop will match -`/usr/share/applications/kde/foo.desktop`). - - - a new #GDesktopAppInfo, or %NULL if no desktop - file with that id exists. - - - - - the desktop file id - - - - - - Creates a new #GDesktopAppInfo. - - - a new #GDesktopAppInfo or %NULL on error. - - - - - the path of a desktop file, in the GLib - filename encoding - - - - - - Creates a new #GDesktopAppInfo. - - - a new #GDesktopAppInfo or %NULL on error. - - - - - an opened #GKeyFile - - - - - - Gets all applications that implement @interface. - -An application implements an interface if that interface is listed in -the Implements= line of the desktop file of the application. - - - a list of #GDesktopAppInfo -objects. - - - - - - - the name of the interface - - - - - - Searches desktop files for ones that match @search_string. - -The return value is an array of strvs. Each strv contains a list of -applications that matched @search_string with an equal score. The -outer list is sorted by score so that the first strv contains the -best-matching applications, and so on. -The algorithm for determining matches is undefined and may change at -any time. - - - a - list of strvs. Free each item with g_strfreev() and free the outer - list with g_free(). - - - - - - - - - the search string to use - - - - - - Sets the name of the desktop that the application is running in. -This is used by g_app_info_should_show() and -g_desktop_app_info_get_show_in() to evaluate the -`OnlyShowIn` and `NotShowIn` -desktop entry fields. - -Should be called only once; subsequent calls are ignored. - do not use this API. Since 2.42 the value of the -`XDG_CURRENT_DESKTOP` environment variable will be used. - - - - - - - a string specifying what desktop this is - - - - - - Gets the user-visible display name of the "additional application -action" specified by @action_name. - -This corresponds to the "Name" key within the keyfile group for the -action. - - - the locale-specific action name - - - - - a #GDesktopAppInfo - - - - the name of the action as from - g_desktop_app_info_list_actions() - - - - - - Looks up a boolean value in the keyfile backing @info. - -The @key is looked up in the "Desktop Entry" group. - - - the boolean value, or %FALSE if the key - is not found - - - - - a #GDesktopAppInfo - - - - the key to look up - - - - - - Gets the categories from the desktop file. - - - The unparsed Categories key from the desktop file; - i.e. no attempt is made to split it by ';' or validate it. - - - - - a #GDesktopAppInfo - - - - - - When @info was created from a known filename, return it. In some -situations such as the #GDesktopAppInfo returned from -g_desktop_app_info_new_from_keyfile(), this function will return %NULL. - - - The full path to the file for @info, - or %NULL if not known. - - - - - a #GDesktopAppInfo - - - - - - Gets the generic name from the destkop file. - - - The value of the GenericName key - - - - - a #GDesktopAppInfo - - - - - - A desktop file is hidden if the Hidden key in it is -set to True. - - - %TRUE if hidden, %FALSE otherwise. - - - - - a #GDesktopAppInfo. - - - - - - Gets the keywords from the desktop file. - - - The value of the Keywords key - - - - - - - a #GDesktopAppInfo - - - - - - Looks up a localized string value in the keyfile backing @info -translated to the current locale. - -The @key is looked up in the "Desktop Entry" group. - - - a newly allocated string, or %NULL if the key - is not found - - - - - a #GDesktopAppInfo - - - - the key to look up - - - - - - Gets the value of the NoDisplay key, which helps determine if the -application info should be shown in menus. See -#G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). - - - The value of the NoDisplay key - - - - - a #GDesktopAppInfo - - - - - - Checks if the application info should be shown in menus that list available -applications for a specific name of the desktop, based on the -`OnlyShowIn` and `NotShowIn` keys. - -@desktop_env should typically be given as %NULL, in which case the -`XDG_CURRENT_DESKTOP` environment variable is consulted. If you want -to override the default mechanism then you may specify @desktop_env, -but this is not recommended. - -Note that g_app_info_should_show() for @info will include this check (with -%NULL for @desktop_env) as well as additional checks. - - - %TRUE if the @info should be shown in @desktop_env according to the -`OnlyShowIn` and `NotShowIn` keys, %FALSE -otherwise. - - - - - a #GDesktopAppInfo - - - - a string specifying a desktop name - - - - - - Retrieves the StartupWMClass field from @info. This represents the -WM_CLASS property of the main window of the application, if launched -through @info. - - - the startup WM class, or %NULL if none is set -in the desktop file. - - - - - a #GDesktopAppInfo that supports startup notify - - - - - - Looks up a string value in the keyfile backing @info. - -The @key is looked up in the "Desktop Entry" group. - - - a newly allocated string, or %NULL if the key - is not found - - - - - a #GDesktopAppInfo - - - - the key to look up - - - - - - Looks up a string list value in the keyfile backing @info. - -The @key is looked up in the "Desktop Entry" group. - - - - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). - - - - - - - a #GDesktopAppInfo - - - - the key to look up - - - - return location for the number of returned strings, or %NULL - - - - - - Returns whether @key exists in the "Desktop Entry" group -of the keyfile backing @info. - - - %TRUE if the @key exists - - - - - a #GDesktopAppInfo - - - - the key to look up - - - - - - Activates the named application action. - -You may only call this function on action names that were -returned from g_desktop_app_info_list_actions(). - -Note that if the main entry of the desktop file indicates that the -application supports startup notification, and @launch_context is -non-%NULL, then startup notification will be used when activating the -action (and as such, invocation of the action on the receiving side -must signal the end of startup notification when it is completed). -This is the expected behaviour of applications declaring additional -actions, as per the desktop file specification. - -As with g_app_info_launch() there is no way to detect failures that -occur while using this function. - - - - - - - a #GDesktopAppInfo - - - - the name of the action as from - g_desktop_app_info_list_actions() - - - - a #GAppLaunchContext - - - - - - This function performs the equivalent of g_app_info_launch_uris(), -but is intended primarily for operating system components that -launch applications. Ordinary applications should use -g_app_info_launch_uris(). - -If the application is launched via GSpawn, then @spawn_flags, @user_setup -and @user_setup_data are used for the call to g_spawn_async(). -Additionally, @pid_callback (with @pid_callback_data) will be called to -inform about the PID of the created process. See g_spawn_async_with_pipes() -for information on certain parameter conditions that can enable an -optimized posix_spawn() codepath to be used. - -If application launching occurs via some other mechanism (eg: D-Bus -activation) then @spawn_flags, @user_setup, @user_setup_data, -@pid_callback and @pid_callback_data are ignored. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GDesktopAppInfo - - - - List of URIs - - - - - - a #GAppLaunchContext - - - - #GSpawnFlags, used for each process - - - - a #GSpawnChildSetupFunc, used once - for each process. - - - - User data for @user_setup - - - - Callback for child processes - - - - User data for @callback - - - - - - Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows -you to pass in file descriptors for the stdin, stdout and stderr streams -of the launched process. - -If application launching occurs via some non-spawn mechanism (e.g. D-Bus -activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - - - %TRUE on successful launch, %FALSE otherwise. - - - - - a #GDesktopAppInfo - - - - List of URIs - - - - - - a #GAppLaunchContext - - - - #GSpawnFlags, used for each process - - - - a #GSpawnChildSetupFunc, used once - for each process. - - - - User data for @user_setup - - - - Callback for child processes - - - - User data for @callback - - - - file descriptor to use for child's stdin, or -1 - - - - file descriptor to use for child's stdout, or -1 - - - - file descriptor to use for child's stderr, or -1 - - - - - - Returns the list of "additional application actions" supported on the -desktop file, as per the desktop file specification. - -As per the specification, this is the list of actions that are -explicitly listed in the "Actions" key of the [Desktop Entry] group. - - - a list of strings, always non-%NULL - - - - - - - a #GDesktopAppInfo - - - - - - The origin filename of this #GDesktopAppInfo - - - - - - - - - - - #GDesktopAppInfoLookup is an opaque data structure and can only be accessed -using the following functions. - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - - - Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup -implementation. - -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends -in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - - - #GAppInfo for given @uri_scheme or %NULL on error. - - - - - a #GDesktopAppInfoLookup - - - - a string containing a URI scheme. - - - - - - Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup -implementation. - -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends -in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. - - - #GAppInfo for given @uri_scheme or %NULL on error. - - - - - a #GDesktopAppInfoLookup - - - - a string containing a URI scheme. - - - - - - - Interface that is used by backends to associate default -handlers with URI schemes. - - - - - - - - - #GAppInfo for given @uri_scheme or %NULL on error. - - - - - a #GDesktopAppInfoLookup - - - - a string containing a URI scheme. - - - - - - - - During invocation, g_desktop_app_info_launch_uris_as_manager() may -create one or more child processes. This callback is invoked once -for each, providing the process ID. - - - - - - - a #GDesktopAppInfo - - - - Process identifier - - - - User data - - - - - - #GDrive - this represent a piece of hardware connected to the machine. -It's generally only created for removable hardware or hardware with -removable media. - -#GDrive is a container class for #GVolume objects that stem from -the same piece of media. As such, #GDrive abstracts a drive with -(or without) removable media and provides operations for querying -whether media is available, determining whether media change is -automatically detected and ejecting the media. - -If the #GDrive reports that media isn't automatically detected, one -can poll for media; typically one should not do this periodically -as a poll for media operation is potententially expensive and may -spin up the drive creating noise. - -#GDrive supports starting and stopping drives with authentication -support for the former. This can be used to support a diverse set -of use cases including connecting/disconnecting iSCSI devices, -powering down external disk enclosures and starting/stopping -multi-disk devices such as RAID devices. Note that the actual -semantics and side-effects of starting/stopping a #GDrive may vary -according to implementation. To choose the correct verbs in e.g. a -file manager, use g_drive_get_start_stop_type(). - -For porting from GnomeVFS note that there is no equivalent of -#GDrive in that API. - - - Checks if a drive can be ejected. - - - %TRUE if the @drive can be ejected, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be polled for media changes. - - - %TRUE if the @drive can be polled for media changes, - %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be started. - - - %TRUE if the @drive can be started, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be started degraded. - - - %TRUE if the @drive can be started degraded, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be stopped. - - - %TRUE if the @drive can be stopped, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - - - - - - - - - - - - - - - - - - - Asynchronously ejects a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_eject_finish() to obtain the -result of the operation. - Use g_drive_eject_with_operation() instead. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - - - - - - - - Finishes ejecting a drive. - Use g_drive_eject_with_operation_finish() instead. - - - %TRUE if the drive has been ejected successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Ejects a drive. This is an asynchronous operation, and is -finished by calling g_drive_eject_with_operation_finish() with the @drive -and #GAsyncResult data returned in the @callback. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a drive. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the drive was successfully ejected. %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Gets the kinds of identifiers that @drive has. -Use g_drive_get_identifier() to obtain the identifiers -themselves. - - - a %NULL-terminated - array of strings containing kinds of identifiers. Use g_strfreev() - to free. - - - - - - - a #GDrive - - - - - - Gets the icon for @drive. - - - #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - Gets the identifier of the given kind for @drive. The only -identifier currently available is -#G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. - - - a newly allocated string containing the - requested identifier, or %NULL if the #GDrive - doesn't have this kind of identifier. - - - - - a #GDrive - - - - the kind of identifier to return - - - - - - Gets the name of @drive. - - - a string containing @drive's name. The returned - string should be freed when no longer needed. - - - - - a #GDrive. - - - - - - Gets the sort key for @drive, if any. - - - Sorting key for @drive or %NULL if no such key is available. - - - - - A #GDrive. - - - - - - Gets a hint about how a drive can be started/stopped. - - - A value from the #GDriveStartStopType enumeration. - - - - - a #GDrive. - - - - - - Gets the icon for @drive. - - - symbolic #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - Get a list of mountable volumes for @drive. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - #GList containing any #GVolume objects on the given @drive. - - - - - - - a #GDrive. - - - - - - Checks if the @drive has media. Note that the OS may not be polling -the drive for media changes; see g_drive_is_media_check_automatic() -for more details. - - - %TRUE if @drive has media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Check if @drive has any mountable volumes. - - - %TRUE if the @drive contains volumes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if @drive is capabable of automatically detecting media changes. - - - %TRUE if the @drive is capabable of automatically detecting - media changes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if the @drive supports removable media. - - - %TRUE if @drive supports removable media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if the #GDrive and/or its media is considered removable by the user. -See g_drive_is_media_removable(). - - - %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Asynchronously polls @drive to see if media has been inserted or removed. - -When the operation is finished, @callback will be called. -You can then call g_drive_poll_for_media_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes an operation started with g_drive_poll_for_media() on a drive. - - - %TRUE if the drive has been poll_for_mediaed successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Asynchronously starts a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_start_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - flags affecting the start operation. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes starting a drive. - - - %TRUE if the drive has been started successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Asynchronously stops a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_stop_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for stopping. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - - - - - - - - Finishes stopping a drive. - - - %TRUE if the drive has been stopped successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Checks if a drive can be ejected. - - - %TRUE if the @drive can be ejected, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be polled for media changes. - - - %TRUE if the @drive can be polled for media changes, - %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be started. - - - %TRUE if the @drive can be started, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be started degraded. - - - %TRUE if the @drive can be started degraded, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if a drive can be stopped. - - - %TRUE if the @drive can be stopped, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Asynchronously ejects a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_eject_finish() to obtain the -result of the operation. - Use g_drive_eject_with_operation() instead. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes ejecting a drive. - Use g_drive_eject_with_operation_finish() instead. - - - %TRUE if the drive has been ejected successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Ejects a drive. This is an asynchronous operation, and is -finished by calling g_drive_eject_with_operation_finish() with the @drive -and #GAsyncResult data returned in the @callback. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a drive. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the drive was successfully ejected. %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Gets the kinds of identifiers that @drive has. -Use g_drive_get_identifier() to obtain the identifiers -themselves. - - - a %NULL-terminated - array of strings containing kinds of identifiers. Use g_strfreev() - to free. - - - - - - - a #GDrive - - - - - - Gets the icon for @drive. - - - #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - Gets the identifier of the given kind for @drive. The only -identifier currently available is -#G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. - - - a newly allocated string containing the - requested identifier, or %NULL if the #GDrive - doesn't have this kind of identifier. - - - - - a #GDrive - - - - the kind of identifier to return - - - - - - Gets the name of @drive. - - - a string containing @drive's name. The returned - string should be freed when no longer needed. - - - - - a #GDrive. - - - - - - Gets the sort key for @drive, if any. - - - Sorting key for @drive or %NULL if no such key is available. - - - - - A #GDrive. - - - - - - Gets a hint about how a drive can be started/stopped. - - - A value from the #GDriveStartStopType enumeration. - - - - - a #GDrive. - - - - - - Gets the icon for @drive. - - - symbolic #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - Get a list of mountable volumes for @drive. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - #GList containing any #GVolume objects on the given @drive. - - - - - - - a #GDrive. - - - - - - Checks if the @drive has media. Note that the OS may not be polling -the drive for media changes; see g_drive_is_media_check_automatic() -for more details. - - - %TRUE if @drive has media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Check if @drive has any mountable volumes. - - - %TRUE if the @drive contains volumes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if @drive is capabable of automatically detecting media changes. - - - %TRUE if the @drive is capabable of automatically detecting - media changes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if the @drive supports removable media. - - - %TRUE if @drive supports removable media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Checks if the #GDrive and/or its media is considered removable by the user. -See g_drive_is_media_removable(). - - - %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. - - - - - a #GDrive. - - - - - - Asynchronously polls @drive to see if media has been inserted or removed. - -When the operation is finished, @callback will be called. -You can then call g_drive_poll_for_media_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes an operation started with g_drive_poll_for_media() on a drive. - - - %TRUE if the drive has been poll_for_mediaed successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Asynchronously starts a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_start_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - flags affecting the start operation. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes starting a drive. - - - %TRUE if the drive has been started successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Asynchronously stops a drive. - -When the operation is finished, @callback will be called. -You can then call g_drive_stop_finish() to obtain the -result of the operation. - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for stopping. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - Finishes stopping a drive. - - - %TRUE if the drive has been stopped successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - Emitted when the drive's state has changed. - - - - - - This signal is emitted when the #GDrive have been -disconnected. If the recipient is holding references to the -object they should release them so the object can be -finalized. - - - - - - Emitted when the physical eject button (if any) of a drive has -been pressed. - - - - - - Emitted when the physical stop button (if any) of a drive has -been pressed. - - - - - - - Interface for creating #GDrive implementations. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a string containing @drive's name. The returned - string should be freed when no longer needed. - - - - - a #GDrive. - - - - - - - - - - #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive contains volumes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - #GList containing any #GVolume objects on the given @drive. - - - - - - - a #GDrive. - - - - - - - - - - %TRUE if @drive supports removable media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - %TRUE if @drive has media, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive is capabable of automatically detecting - media changes, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive can be ejected, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive can be polled for media changes, - %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - %TRUE if the drive has been ejected successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GDrive. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - %TRUE if the drive has been poll_for_mediaed successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - - - - - a newly allocated string containing the - requested identifier, or %NULL if the #GDrive - doesn't have this kind of identifier. - - - - - a #GDrive - - - - the kind of identifier to return - - - - - - - - - - a %NULL-terminated - array of strings containing kinds of identifiers. Use g_strfreev() - to free. - - - - - - - a #GDrive - - - - - - - - - - A value from the #GDriveStartStopType enumeration. - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive can be started, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - %TRUE if the @drive can be started degraded, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - - - - - a #GDrive. - - - - flags affecting the start operation. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - %TRUE if the drive has been started successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - - - - - %TRUE if the @drive can be stopped, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for stopping. - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data to pass to @callback - - - - - - - - - - %TRUE if the drive has been stopped successfully, - %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GDrive. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the drive was successfully ejected. %FALSE otherwise. - - - - - a #GDrive. - - - - a #GAsyncResult. - - - - - - - - - - Sorting key for @drive or %NULL if no such key is available. - - - - - A #GDrive. - - - - - - - - - - symbolic #GIcon for the @drive. - Free the returned object with g_object_unref(). - - - - - a #GDrive. - - - - - - - - - - %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. - - - - - a #GDrive. - - - - - - - - Flags used when starting a drive. - - No flags set. - - - - Enumeration describing how a drive can be started/stopped. - - Unknown or drive doesn't support - start/stop. - - - The stop method will physically - shut down the drive and e.g. power down the port the drive is - attached to. - - - The start/stop methods are used - for connecting/disconnect to the drive over the network. - - - The start/stop methods will - assemble/disassemble a virtual drive from several physical - drives. - - - The start/stop methods will - unlock/lock the disk (for example using the ATA <quote>SECURITY - UNLOCK DEVICE</quote> command) - - - - #GDtlsClientConnection is the client-side subclass of -#GDtlsConnection, representing a client-side DTLS connection. - - - - - Creates a new #GDtlsClientConnection wrapping @base_socket which is -assumed to communicate with the server identified by @server_identity. - - - the new - #GDtlsClientConnection, or %NULL on error - - - - - the #GDatagramBased to wrap - - - - the expected identity of the server - - - - - - Gets the list of distinguished names of the Certificate Authorities -that the server will accept certificates from. This will be set -during the TLS handshake if the server requests a certificate. -Otherwise, it will be %NULL. - -Each item in the list is a #GByteArray which contains the complete -subject DN of the certificate authority. - - - the list of -CA DNs. You should unref each element with g_byte_array_unref() and then -the free the list with g_list_free(). - - - - - - - - - the #GDtlsClientConnection - - - - - - Gets @conn's expected server identity - - - a #GSocketConnectable describing the -expected server identity, or %NULL if the expected identity is not -known. - - - - - the #GDtlsClientConnection - - - - - - Gets @conn's validation flags - - - the validation flags - - - - - the #GDtlsClientConnection - - - - - - Sets @conn's expected server identity, which is used both to tell -servers on virtual hosts which certificate to present, and also -to let @conn know what name to look for in the certificate when -performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - - - - - - - the #GDtlsClientConnection - - - - a #GSocketConnectable describing the expected server identity - - - - - - Sets @conn's validation flags, to override the default set of -checks performed when validating a server certificate. By default, -%G_TLS_CERTIFICATE_VALIDATE_ALL is used. - - - - - - - the #GDtlsClientConnection - - - - the #GTlsCertificateFlags to use - - - - - - A list of the distinguished names of the Certificate Authorities -that the server will accept client certificates signed by. If the -server requests a client certificate during the handshake, then -this property will be set after the handshake completes. - -Each item in the list is a #GByteArray which contains the complete -subject DN of the certificate authority. - - - - - - A #GSocketConnectable describing the identity of the server that -is expected on the other end of the connection. - -If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in -#GDtlsClientConnection:validation-flags, this object will be used -to determine the expected identify of the remote end of the -connection; if #GDtlsClientConnection:server-identity is not set, -or does not match the identity presented by the server, then the -%G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. - -In addition to its use in verifying the server certificate, -this is also used to give a hint to the server about what -certificate we expect, which is useful for servers that serve -virtual hosts. - - - - What steps to perform when validating a certificate received from -a server. Server certificates that fail to validate in all of the -ways indicated here will be rejected unless the application -overrides the default via #GDtlsConnection::accept-certificate. - - - - - vtable for a #GDtlsClientConnection implementation. - - - The parent interface. - - - - - #GDtlsConnection is the base DTLS connection class type, which wraps -a #GDatagramBased and provides DTLS encryption on top of it. Its -subclasses, #GDtlsClientConnection and #GDtlsServerConnection, -implement client-side and server-side DTLS, respectively. - -For TLS support, see #GTlsConnection. - -As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased, -presenting a datagram-socket-like API for the encrypted connection. This -operates over a base datagram connection, which is also a #GDatagramBased -(#GDtlsConnection:base-socket). - -To close a DTLS connection, use g_dtls_connection_close(). - -Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address -on their base #GDatagramBased if it is a #GSocket — it is up to the caller to -do that if they wish. If they do not, and g_socket_close() is called on the -base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED -error on further I/O. - - - - - - - - - - - - - - - - - - - - - Gets the name of the application-layer protocol negotiated during -the handshake. - -If the peer did not use the ALPN extension, or did not advertise a -protocol that matched one of @conn's protocols, or the TLS backend -does not support ALPN, then this will be %NULL. See -g_dtls_connection_set_advertised_protocols(). - - - the negotiated protocol, or %NULL - - - - - a #GDtlsConnection - - - - - - Attempts a TLS handshake on @conn. - -On the client side, it is never necessary to call this method; -although the connection needs to perform a handshake after -connecting, #GDtlsConnection will handle this for you automatically -when you try to send or receive data on the connection. You can call -g_dtls_connection_handshake() manually if you want to know whether -the initial handshake succeeded or failed (as opposed to just -immediately trying to use @conn to read or write, in which case, -if it fails, it may not be possible to tell if it failed before -or after completing the handshake), but beware that servers may reject -client authentication after the handshake has completed, so a -successful handshake does not indicate the connection will be usable. - -Likewise, on the server side, although a handshake is necessary at -the beginning of the communication, you do not need to call this -function explicitly unless you want clearer error reporting. - -Previously, calling g_dtls_connection_handshake() after the initial -handshake would trigger a rehandshake; however, this usage was -deprecated in GLib 2.60 because rehandshaking was removed from the -TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after -the initial handshake will no longer do anything. - -#GDtlsConnection::accept_certificate may be emitted during the -handshake. - - - success or failure - - - - - a #GDtlsConnection - - - - a #GCancellable, or %NULL - - - - - - Asynchronously performs a TLS handshake on @conn. See -g_dtls_connection_handshake() for more information. - - - - - - - a #GDtlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS handshake operation. See -g_dtls_connection_handshake() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GDtlsConnection - - - - a #GAsyncResult. - - - - - - Sets the list of application-layer protocols to advertise that the -caller is willing to speak on this connection. The -Application-Layer Protocol Negotiation (ALPN) extension will be -used to negotiate a compatible protocol with the peer; use -g_dtls_connection_get_negotiated_protocol() to find the negotiated -protocol after the handshake. Specifying %NULL for the the value -of @protocols will disable ALPN negotiation. - -See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) -for a list of registered protocol IDs. - - - - - - - a #GDtlsConnection - - - - a %NULL-terminated - array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - - - - - - - - Shut down part or all of a DTLS connection. - -If @shutdown_read is %TRUE then the receiving side of the connection is shut -down, and further reading is disallowed. Subsequent calls to -g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. - -If @shutdown_write is %TRUE then the sending side of the connection is shut -down, and further writing is disallowed. Subsequent calls to -g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. - -It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this -is equivalent to calling g_dtls_connection_close(). - -If @cancellable is cancelled, the #GDtlsConnection may be left -partially-closed and any pending untransmitted data may be lost. Call -g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. - - - %TRUE on success, %FALSE otherwise - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - a #GCancellable, or %NULL - - - - - - Asynchronously shut down part or all of the DTLS connection. See -g_dtls_connection_shutdown() for more information. - - - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the shutdown operation is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS shutdown operation. See -g_dtls_connection_shutdown() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set - - - - - a #GDtlsConnection - - - - a #GAsyncResult - - - - - - Close the DTLS connection. This is equivalent to calling -g_dtls_connection_shutdown() to shut down both sides of the connection. - -Closing a #GDtlsConnection waits for all buffered but untransmitted data to -be sent before it completes. It then sends a `close_notify` DTLS alert to the -peer and may wait for a `close_notify` to be received from the peer. It does -not close the underlying #GDtlsConnection:base-socket; that must be closed -separately. - -Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED. -Closing a #GDtlsConnection multiple times will not return an error. - -#GDtlsConnections will be automatically closed when the last reference is -dropped, but you might want to call this function to make sure resources are -released as early as possible. - -If @cancellable is cancelled, the #GDtlsConnection may be left -partially-closed and any pending untransmitted data may be lost. Call -g_dtls_connection_close() again to complete closing the #GDtlsConnection. - - - %TRUE on success, %FALSE otherwise - - - - - a #GDtlsConnection - - - - a #GCancellable, or %NULL - - - - - - Asynchronously close the DTLS connection. See g_dtls_connection_close() for -more information. - - - - - - - a #GDtlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the close operation is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS close operation. See g_dtls_connection_close() -for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set - - - - - a #GDtlsConnection - - - - a #GAsyncResult - - - - - - Used by #GDtlsConnection implementations to emit the -#GDtlsConnection::accept-certificate signal. - - - %TRUE if one of the signal handlers has returned - %TRUE to accept @peer_cert - - - - - a #GDtlsConnection - - - - the peer's #GTlsCertificate - - - - the problems with @peer_cert - - - - - - Gets @conn's certificate, as set by -g_dtls_connection_set_certificate(). - - - @conn's certificate, or %NULL - - - - - a #GDtlsConnection - - - - - - Gets the certificate database that @conn uses to verify -peer certificates. See g_dtls_connection_set_database(). - - - the certificate database that @conn uses or %NULL - - - - - a #GDtlsConnection - - - - - - Get the object that will be used to interact with the user. It will be used -for things like prompting the user for passwords. If %NULL is returned, then -no user interaction will occur for this connection. - - - The interaction object. - - - - - a connection - - - - - - Gets the name of the application-layer protocol negotiated during -the handshake. - -If the peer did not use the ALPN extension, or did not advertise a -protocol that matched one of @conn's protocols, or the TLS backend -does not support ALPN, then this will be %NULL. See -g_dtls_connection_set_advertised_protocols(). - - - the negotiated protocol, or %NULL - - - - - a #GDtlsConnection - - - - - - Gets @conn's peer's certificate after the handshake has completed. -(It is not set during the emission of -#GDtlsConnection::accept-certificate.) - - - @conn's peer's certificate, or %NULL - - - - - a #GDtlsConnection - - - - - - Gets the errors associated with validating @conn's peer's -certificate, after the handshake has completed. (It is not set -during the emission of #GDtlsConnection::accept-certificate.) - - - @conn's peer's certificate errors - - - - - a #GDtlsConnection - - - - - - Gets @conn rehandshaking mode. See -g_dtls_connection_set_rehandshake_mode() for details. - Changing the rehandshake mode is no longer - required for compatibility. Also, rehandshaking has been removed - from the TLS protocol in TLS 1.3. - - - %G_TLS_REHANDSHAKE_SAFELY - - - - - a #GDtlsConnection - - - - - - Tests whether or not @conn expects a proper TLS close notification -when the connection is closed. See -g_dtls_connection_set_require_close_notify() for details. - - - %TRUE if @conn requires a proper TLS close notification. - - - - - a #GDtlsConnection - - - - - - Attempts a TLS handshake on @conn. - -On the client side, it is never necessary to call this method; -although the connection needs to perform a handshake after -connecting, #GDtlsConnection will handle this for you automatically -when you try to send or receive data on the connection. You can call -g_dtls_connection_handshake() manually if you want to know whether -the initial handshake succeeded or failed (as opposed to just -immediately trying to use @conn to read or write, in which case, -if it fails, it may not be possible to tell if it failed before -or after completing the handshake), but beware that servers may reject -client authentication after the handshake has completed, so a -successful handshake does not indicate the connection will be usable. - -Likewise, on the server side, although a handshake is necessary at -the beginning of the communication, you do not need to call this -function explicitly unless you want clearer error reporting. - -Previously, calling g_dtls_connection_handshake() after the initial -handshake would trigger a rehandshake; however, this usage was -deprecated in GLib 2.60 because rehandshaking was removed from the -TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after -the initial handshake will no longer do anything. - -#GDtlsConnection::accept_certificate may be emitted during the -handshake. - - - success or failure - - - - - a #GDtlsConnection - - - - a #GCancellable, or %NULL - - - - - - Asynchronously performs a TLS handshake on @conn. See -g_dtls_connection_handshake() for more information. - - - - - - - a #GDtlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS handshake operation. See -g_dtls_connection_handshake() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GDtlsConnection - - - - a #GAsyncResult. - - - - - - Sets the list of application-layer protocols to advertise that the -caller is willing to speak on this connection. The -Application-Layer Protocol Negotiation (ALPN) extension will be -used to negotiate a compatible protocol with the peer; use -g_dtls_connection_get_negotiated_protocol() to find the negotiated -protocol after the handshake. Specifying %NULL for the the value -of @protocols will disable ALPN negotiation. - -See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) -for a list of registered protocol IDs. - - - - - - - a #GDtlsConnection - - - - a %NULL-terminated - array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - - - - - - - - This sets the certificate that @conn will present to its peer -during the TLS handshake. For a #GDtlsServerConnection, it is -mandatory to set this, and that will normally be done at construct -time. - -For a #GDtlsClientConnection, this is optional. If a handshake fails -with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server -requires a certificate, and if you try connecting again, you should -call this method first. You can call -g_dtls_client_connection_get_accepted_cas() on the failed connection -to get a list of Certificate Authorities that the server will -accept certificates from. - -(It is also possible that a server will allow the connection with -or without a certificate; in that case, if you don't provide a -certificate, you can tell that the server requested one by the fact -that g_dtls_client_connection_get_accepted_cas() will return -non-%NULL.) - - - - - - - a #GDtlsConnection - - - - the certificate to use for @conn - - - - - - Sets the certificate database that is used to verify peer certificates. -This is set to the default database by default. See -g_tls_backend_get_default_database(). If set to %NULL, then -peer certificate validation will always set the -%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning -#GDtlsConnection::accept-certificate will always be emitted on -client-side connections, unless that bit is not set in -#GDtlsClientConnection:validation-flags). - - - - - - - a #GDtlsConnection - - - - a #GTlsDatabase - - - - - - Set the object that will be used to interact with the user. It will be used -for things like prompting the user for passwords. - -The @interaction argument will normally be a derived subclass of -#GTlsInteraction. %NULL can also be provided if no user interaction -should occur for this connection. - - - - - - - a connection - - - - an interaction object, or %NULL - - - - - - Since GLib 2.64, changing the rehandshake mode is no longer supported -and will have no effect. With TLS 1.3, rehandshaking has been removed from -the TLS protocol, replaced by separate post-handshake authentication and -rekey operations. - Changing the rehandshake mode is no longer - required for compatibility. Also, rehandshaking has been removed - from the TLS protocol in TLS 1.3. - - - - - - - a #GDtlsConnection - - - - the rehandshaking mode - - - - - - Sets whether or not @conn expects a proper TLS close notification -before the connection is closed. If this is %TRUE (the default), -then @conn will expect to receive a TLS close notification from its -peer before the connection is closed, and will return a -%G_TLS_ERROR_EOF error if the connection is closed without proper -notification (since this may indicate a network error, or -man-in-the-middle attack). - -In some protocols, the application will know whether or not the -connection was closed cleanly based on application-level data -(because the application-level data includes a length field, or is -somehow self-delimiting); in this case, the close notify is -redundant and may be omitted. You -can use g_dtls_connection_set_require_close_notify() to tell @conn -to allow an "unannounced" connection close, in which case the close -will show up as a 0-length read, as in a non-TLS -#GDatagramBased, and it is up to the application to check that -the data has been fully received. - -Note that this only affects the behavior when the peer closes the -connection; when the application calls g_dtls_connection_close_async() on -@conn itself, this will send a close notification regardless of the -setting of this property. If you explicitly want to do an unclean -close, you can close @conn's #GDtlsConnection:base-socket rather -than closing @conn itself. - - - - - - - a #GDtlsConnection - - - - whether or not to require close notification - - - - - - Shut down part or all of a DTLS connection. - -If @shutdown_read is %TRUE then the receiving side of the connection is shut -down, and further reading is disallowed. Subsequent calls to -g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. - -If @shutdown_write is %TRUE then the sending side of the connection is shut -down, and further writing is disallowed. Subsequent calls to -g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. - -It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this -is equivalent to calling g_dtls_connection_close(). - -If @cancellable is cancelled, the #GDtlsConnection may be left -partially-closed and any pending untransmitted data may be lost. Call -g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. - - - %TRUE on success, %FALSE otherwise - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - a #GCancellable, or %NULL - - - - - - Asynchronously shut down part or all of the DTLS connection. See -g_dtls_connection_shutdown() for more information. - - - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the shutdown operation is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS shutdown operation. See -g_dtls_connection_shutdown() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set - - - - - a #GDtlsConnection - - - - a #GAsyncResult - - - - - - The list of application-layer protocols that the connection -advertises that it is willing to speak. See -g_dtls_connection_set_advertised_protocols(). - - - - - - The #GDatagramBased that the connection wraps. Note that this may be any -implementation of #GDatagramBased, not just a #GSocket. - - - - The connection's certificate; see -g_dtls_connection_set_certificate(). - - - - The certificate database to use when verifying this TLS connection. -If no certificate database is set, then the default database will be -used. See g_tls_backend_get_default_database(). - - - - A #GTlsInteraction object to be used when the connection or certificate -database need to interact with the user. This will be used to prompt the -user for passwords where necessary. - - - - The application-layer protocol negotiated during the TLS -handshake. See g_dtls_connection_get_negotiated_protocol(). - - - - The connection's peer's certificate, after the TLS handshake has -completed and the certificate has been accepted. Note in -particular that this is not yet set during the emission of -#GDtlsConnection::accept-certificate. - -(You can watch for a #GObject::notify signal on this property to -detect when a handshake has occurred.) - - - - The errors noticed-and-ignored while verifying -#GDtlsConnection:peer-certificate. Normally this should be 0, but -it may not be if #GDtlsClientConnection:validation-flags is not -%G_TLS_CERTIFICATE_VALIDATE_ALL, or if -#GDtlsConnection::accept-certificate overrode the default -behavior. - - - - The rehandshaking mode. See -g_dtls_connection_set_rehandshake_mode(). - The rehandshake mode is ignored. - - - - Whether or not proper TLS close notification is required. -See g_dtls_connection_set_require_close_notify(). - - - - Emitted during the TLS handshake after the peer certificate has -been received. You can examine @peer_cert's certification path by -calling g_tls_certificate_get_issuer() on it. - -For a client-side connection, @peer_cert is the server's -certificate, and the signal will only be emitted if the -certificate was not acceptable according to @conn's -#GDtlsClientConnection:validation_flags. If you would like the -certificate to be accepted despite @errors, return %TRUE from the -signal handler. Otherwise, if no handler accepts the certificate, -the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. - -For a server-side connection, @peer_cert is the certificate -presented by the client, if this was requested via the server's -#GDtlsServerConnection:authentication_mode. On the server side, -the signal is always emitted when the client presents a -certificate, and the certificate will only be accepted if a -handler returns %TRUE. - -Note that if this signal is emitted as part of asynchronous I/O -in the main thread, then you should not attempt to interact with -the user before returning from the signal handler. If you want to -let the user decide whether or not to accept the certificate, you -would have to return %FALSE from the signal handler on the first -attempt, and then after the connection attempt returns a -%G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and -if the user decides to accept the certificate, remember that fact, -create a new connection, and return %TRUE from the signal handler -the next time. - -If you are doing I/O in another thread, you do not -need to worry about this, and can simply block in the signal -handler until the UI thread returns an answer. - - %TRUE to accept @peer_cert (which will also -immediately end the signal emission). %FALSE to allow the signal -emission to continue, which will cause the handshake to fail if -no one else overrides it. - - - - - the peer's #GTlsCertificate - - - - the problems with @peer_cert. - - - - - - - Virtual method table for a #GDtlsConnection implementation. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - success or failure - - - - - a #GDtlsConnection - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GDtlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - - - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GDtlsConnection - - - - a #GAsyncResult. - - - - - - - - - - %TRUE on success, %FALSE otherwise - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GDtlsConnection - - - - %TRUE to stop reception of incoming datagrams - - - - %TRUE to stop sending outgoing datagrams - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the shutdown operation is complete - - - - the data to pass to the callback function - - - - - - - - - - %TRUE on success, %FALSE on failure, in which -case @error will be set - - - - - a #GDtlsConnection - - - - a #GAsyncResult - - - - - - - - - - - - - - a #GDtlsConnection - - - - a %NULL-terminated - array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - - - - - - - - - - - - the negotiated protocol, or %NULL - - - - - a #GDtlsConnection - - - - - - - - #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, -representing a server-side DTLS connection. - - - - - Creates a new #GDtlsServerConnection wrapping @base_socket. - - - the new - #GDtlsServerConnection, or %NULL on error - - - - - the #GDatagramBased to wrap - - - - the default server certificate, or %NULL - - - - - - The #GTlsAuthenticationMode for the server. This can be changed -before calling g_dtls_connection_handshake() if you want to -rehandshake with a different mode from the initial handshake. - - - - - vtable for a #GDtlsServerConnection implementation. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GEmblem is an implementation of #GIcon that supports -having an emblem, which is an icon with additional properties. -It can than be added to a #GEmblemedIcon. - -Currently, only metainformation about the emblem's origin is -supported. More may be added in the future. - - - - Creates a new emblem for @icon. - - - a new #GEmblem. - - - - - a GIcon containing the icon. - - - - - - Creates a new emblem for @icon. - - - a new #GEmblem. - - - - - a GIcon containing the icon. - - - - a GEmblemOrigin enum defining the emblem's origin - - - - - - Gives back the icon from @emblem. - - - a #GIcon. The returned object belongs to - the emblem and should not be modified or freed. - - - - - a #GEmblem from which the icon should be extracted. - - - - - - Gets the origin of the emblem. - - - the origin of the emblem - - - - - a #GEmblem - - - - - - - - - - - - - - - - GEmblemOrigin is used to add information about the origin of the emblem -to #GEmblem. - - Emblem of unknown origin - - - Emblem adds device-specific information - - - Emblem depicts live metadata, such as "readonly" - - - Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) - - - - #GEmblemedIcon is an implementation of #GIcon that supports -adding an emblem to an icon. Adding multiple emblems to an -icon is ensured via g_emblemed_icon_add_emblem(). - -Note that #GEmblemedIcon allows no control over the position -of the emblems. See also #GEmblem for more information. - - - - Creates a new emblemed icon for @icon with the emblem @emblem. - - - a new #GIcon - - - - - a #GIcon - - - - a #GEmblem, or %NULL - - - - - - Adds @emblem to the #GList of #GEmblems. - - - - - - - a #GEmblemedIcon - - - - a #GEmblem - - - - - - Removes all the emblems from @icon. - - - - - - - a #GEmblemedIcon - - - - - - Gets the list of emblems for the @icon. - - - a #GList of - #GEmblems that is owned by @emblemed - - - - - - - a #GEmblemedIcon - - - - - - Gets the main icon for @emblemed. - - - a #GIcon that is owned by @emblemed - - - - - a #GEmblemedIcon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A key in the "access" namespace for checking deletion privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to delete the file. - - - - - A key in the "access" namespace for getting execution privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to execute the file. - - - - - A key in the "access" namespace for getting read privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to read the file. - - - - - A key in the "access" namespace for checking renaming privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to rename the file. - - - - - A key in the "access" namespace for checking trashing privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to move the file to -the trash. - - - - - A key in the "access" namespace for getting write privileges. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. -This attribute will be %TRUE if the user is able to write to the file. - - - - - A key in the "dos" namespace for checking if the file's archive flag -is set. This attribute is %TRUE if the archive flag is set. This attribute -is only available for DOS file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "dos" namespace for checking if the file is a NTFS mount point -(a volume mount or a junction point). -This attribute is %TRUE if file is a reparse point of type -[IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx). -This attribute is only available for DOS file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "dos" namespace for checking if the file's backup flag -is set. This attribute is %TRUE if the backup flag is set. This attribute -is only available for DOS file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "dos" namespace for getting the file NTFS reparse tag. -This value is 0 for files that are not reparse points. -See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) -page for possible reparse tag values. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "etag" namespace for getting the value of the file's -entity tag. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "filesystem" namespace for getting the number of bytes of free space left on the -file system. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "filesystem" namespace for checking if the file system -is read only. Is set to %TRUE if the file system is read only. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "filesystem" namespace for checking if the file system -is remote. Is set to %TRUE if the file system is remote. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, -used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "filesystem" namespace for getting the file system's type. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "filesystem" namespace for getting the number of bytes of used on the -file system. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "filesystem" namespace for hinting a file manager -application whether it should preview (e.g. thumbnail) files on the -file system. The value for this key contain a -#GFilesystemPreviewType. - - - - - A key in the "gvfs" namespace that gets the name of the current -GVFS backend in use. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "id" namespace for getting a file identifier. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. -An example use would be during listing files, to avoid recursive -directory scanning. - - - - - A key in the "id" namespace for getting the file system identifier. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. -An example use would be during drag and drop to see if the source -and target are on the same filesystem (default to move) or not (default -to copy). - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started -degraded. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for getting the HAL UDI for the mountable -file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) -is automatically polled for media. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "mountable" namespace for getting the #GDriveStartStopType. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "mountable" namespace for getting the unix device. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "mountable" namespace for getting the unix device file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "owner" namespace for getting the file owner's group. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "owner" namespace for getting the user name of the -file's owner. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "owner" namespace for getting the real name of the -user that owns the file. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "preview" namespace for getting a #GIcon that can be -used to get preview of the file. For example, it may be a low -resolution thumbnail without metadata. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value -for this key should contain a #GIcon. - - - - - A key in the "recent" namespace for getting time, when the metadata for the -file in `recent:///` was last changed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_INT64. - - - - - A key in the "selinux" namespace for getting the file's SELinux -context. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only -available if GLib has been built with SELinux support. - - - - - A key in the "standard" namespace for getting the amount of disk space -that is consumed by the file (in bytes). This will generally be larger -than the file size (due to block size overhead) but can occasionally be -smaller (for example, for sparse files). -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "standard" namespace for getting the content type of the file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. -The value for this key should contain a valid content type. - - - - - A key in the "standard" namespace for getting the copy name of the file. -The copy name is an optional version of the name. If available it's always -in UTF8, and corresponds directly to the original filename (only transcoded to -UTF8). This is useful if you want to copy the file to another filesystem that -might have a different encoding. If the filename is not a valid string in the -encoding selected for the filesystem it is in then the copy name will not be set. - -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for getting the description of the file. -The description is a utf8 string that describes the file, generally containing -the filename, but can also contain furter information. Example descriptions -could be "filename (on hostname)" for a remote file or "filename (in trash)" -for a file in the trash. This is useful for instance as the window title -when displaying a directory or for a bookmarks menu. - -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for getting the display name of the file. -A display name is guaranteed to be in UTF8 and can thus be displayed in -the UI. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for edit name of the file. -An edit name is similar to the display name, but it is meant to be -used when you want to rename the file in the UI. The display name -might contain information you don't want in the new filename (such as -"(invalid unicode)" if the filename was in an invalid encoding). - -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for getting the fast content type. -The fast content type isn't as reliable as the regular one, as it -only uses the filename to guess it, but it is faster to calculate than the -regular content type. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for getting the icon for the file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. -The value for this key should contain a #GIcon. - - - - - A key in the "standard" namespace for checking if a file is a backup file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "standard" namespace for checking if a file is hidden. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "standard" namespace for checking if the file is a symlink. -Typically the actual type is something else, if we followed the symlink -to get the type. -On Windows NTFS mountpoints are considered to be symlinks as well. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "standard" namespace for checking if a file is virtual. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "standard" namespace for checking if a file is -volatile. This is meant for opaque, non-POSIX-like backends to -indicate that the URI is not persistent. Applications should look -at #G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. - -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "standard" namespace for getting the name of the file. -The name is the on-disk filename which may not be in any known encoding, -and can thus not be generally displayed as is. -Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the -name in a user interface. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - - - - - A key in the "standard" namespace for getting the file's size (in bytes). -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "standard" namespace for setting the sort order of a file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. -An example use would be in file managers, which would use this key -to set the order files are displayed. Files with smaller sort order -should be sorted first, and files without sort order as if sort order -was zero. - - - - - A key in the "standard" namespace for getting the symbolic icon for the file. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. -The value for this key should contain a #GIcon. - - - - - A key in the "standard" namespace for getting the symlink target, if the file -is a symlink. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - - - - - A key in the "standard" namespace for getting the target URI for the file, in -the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "standard" namespace for storing file types. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. -The value for this key should contain a #GFileType. - - - - - A key in the "thumbnail" namespace for checking if thumbnailing failed. -This attribute is %TRUE if thumbnailing failed. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. -This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, -and %FALSE if the file has been modified since the thumbnail was generated. - -If %G_FILE_ATTRIBUTE_THUMBNAILING_FAILED is %TRUE and this attribute is %FALSE, -it indicates that thumbnailing may be attempted again and may succeed. - -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "thumbnail" namespace for getting the path to the thumbnail -image. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - - - - - A key in the "time" namespace for getting the time the file was last -accessed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the -file was last accessed, in seconds since the UNIX epoch. - - - - - A key in the "time" namespace for getting the microseconds of the time -the file was last accessed. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "time" namespace for getting the time the file was last -changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, -and contains the time since the file was last changed, in seconds since the -UNIX epoch. - -This corresponds to the traditional UNIX ctime. - - - - - A key in the "time" namespace for getting the microseconds of the time -the file was last changed. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "time" namespace for getting the time the file was created. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, -and contains the time since the file was created, in seconds since the UNIX -epoch. - -This corresponds to the NTFS ctime. - - - - - A key in the "time" namespace for getting the microseconds of the time -the file was created. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "time" namespace for getting the time the file was last -modified. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the -file was modified, in seconds since the UNIX epoch. - - - - - A key in the "time" namespace for getting the microseconds of the time -the file was last modified. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "trash" namespace. When requested against -items in `trash:///`, will return the date and time when the file -was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - - - - - A key in the "trash" namespace. When requested against -`trash:///` returns the number of (toplevel) items in the trash folder. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "trash" namespace. When requested against -items in `trash:///`, will return the original path to the file before it -was trashed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. - - - - - A key in the "unix" namespace for getting the number of blocks allocated -for the file. This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "unix" namespace for getting the block size for the file -system. This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the device id of the device the -file is located on (see stat() documentation). This attribute is only -available for UNIX file systems. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the group ID for the file. -This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the inode of the file. -This attribute is only available for UNIX file systems. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. - - - - - A key in the "unix" namespace for checking if the file represents a -UNIX mount point. This attribute is %TRUE if the file is a UNIX mount -point. Since 2.58, `/` is considered to be a mount point. -This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - - - - - A key in the "unix" namespace for getting the mode of the file -(e.g. whether the file is a regular file, symlink, etc). See the -documentation for `lstat()`: this attribute is equivalent to the `st_mode` -member of `struct stat`, and includes both the file type and permissions. -This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the number of hard links -for a file. See lstat() documentation. This attribute is only available -for UNIX file systems. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the device ID for the file -(if it is a special file). See lstat() documentation. This attribute -is only available for UNIX file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - A key in the "unix" namespace for getting the user ID for the file. -This attribute is only available for UNIX file systems. -Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GFile is a high level abstraction for manipulating files on a -virtual file system. #GFiles are lightweight, immutable objects -that do no I/O upon creation. It is necessary to understand that -#GFile objects do not represent files, merely an identifier for a -file. All file content I/O is implemented as streaming operations -(see #GInputStream and #GOutputStream). - -To construct a #GFile, you can use: -- g_file_new_for_path() if you have a path. -- g_file_new_for_uri() if you have a URI. -- g_file_new_for_commandline_arg() for a command line argument. -- g_file_new_tmp() to create a temporary file from a template. -- g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). -- g_file_new_build_filename() to create a file from path elements. - -One way to think of a #GFile is as an abstraction of a pathname. For -normal files the system pathname is what is stored internally, but as -#GFiles are extensible it could also be something else that corresponds -to a pathname in a userspace implementation of a filesystem. - -#GFiles make up hierarchies of directories and files that correspond to -the files on a filesystem. You can move through the file system with -#GFile using g_file_get_parent() to get an identifier for the parent -directory, g_file_get_child() to get a child within a directory, -g_file_resolve_relative_path() to resolve a relative path between two -#GFiles. There can be multiple hierarchies, so you may not end up at -the same root if you repeatedly call g_file_get_parent() on two different -files. - -All #GFiles have a basename (get with g_file_get_basename()). These names -are byte strings that are used to identify the file on the filesystem -(relative to its parent directory) and there is no guarantees that they -have any particular charset encoding or even make any sense at all. If -you want to use filenames in a user interface you should use the display -name that you can get by requesting the -%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). -This is guaranteed to be in UTF-8 and can be used in a user interface. -But always store the real basename or the #GFile to use to actually -access the file, because there is no way to go from a display name to -the actual name. - -Using #GFile as an identifier has the same weaknesses as using a path -in that there may be multiple aliases for the same file. For instance, -hard or soft links may cause two different #GFiles to refer to the same -file. Other possible causes for aliases are: case insensitive filesystems, -short and long names on FAT/NTFS, or bind mounts in Linux. If you want to -check if two #GFiles point to the same file you can query for the -%G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial -canonicalization of pathnames passed in, so that trivial differences in -the path string used at creation (duplicated slashes, slash at end of -path, "." or ".." path segments, etc) does not create different #GFiles. - -Many #GFile operations have both synchronous and asynchronous versions -to suit your application. Asynchronous versions of synchronous functions -simply have _async() appended to their function names. The asynchronous -I/O functions call a #GAsyncReadyCallback which is then used to finalize -the operation, producing a GAsyncResult which is then passed to the -function's matching _finish() operation. - -It is highly recommended to use asynchronous calls when running within a -shared main loop, such as in the main thread of an application. This avoids -I/O operations blocking other sources on the main loop from being dispatched. -Synchronous I/O operations should be performed from worker threads. See the -[introduction to asynchronous programming section][async-programming] for -more. - -Some #GFile operations almost always take a noticeable amount of time, and -so do not have synchronous analogs. Notable cases include: -- g_file_mount_mountable() to mount a mountable file. -- g_file_unmount_mountable_with_operation() to unmount a mountable file. -- g_file_eject_mountable_with_operation() to eject a mountable file. - -## Entity Tags # {#gfile-etag} - -One notable feature of #GFiles are entity tags, or "etags" for -short. Entity tags are somewhat like a more abstract version of the -traditional mtime, and can be used to quickly determine if the file -has been modified from the version on the file system. See the -HTTP 1.1 -[specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) -for HTTP Etag headers, which are a very similar concept. - - - Constructs a #GFile from a series of elements using the correct -separator for filenames. - -Using this function is equivalent to calling g_build_filename(), -followed by g_file_new_for_path() on the result. - - - a new #GFile - - - - - the first element in the path - - - - remaining elements in path, terminated by %NULL - - - - - - Creates a #GFile with the given argument from the command line. -The value of @arg can be either a URI, an absolute path or a -relative path resolved relative to the current working directory. -This operation never fails, but the returned object might not -support any I/O operation if @arg points to a malformed path. - -Note that on Windows, this function expects its argument to be in -UTF-8 -- not the system code page. This means that you -should not use this function with string from argv as it is passed -to main(). g_win32_get_command_line() will return a UTF-8 version of -the commandline. #GApplication also uses UTF-8 but -g_application_command_line_create_file_for_arg() may be more useful -for you there. It is also always possible to use this function with -#GOptionContext arguments of type %G_OPTION_ARG_FILENAME. - - - a new #GFile. - Free the returned object with g_object_unref(). - - - - - a command line string - - - - - - Creates a #GFile with the given argument from the command line. - -This function is similar to g_file_new_for_commandline_arg() except -that it allows for passing the current working directory as an -argument instead of using the current working directory of the -process. - -This is useful if the commandline argument was given in a context -other than the invocation of the current process. - -See also g_application_command_line_create_file_for_arg(). - - - a new #GFile - - - - - a command line string - - - - the current working directory of the commandline - - - - - - Constructs a #GFile for a given path. This operation never -fails, but the returned object might not support any I/O -operation if @path is malformed. - - - a new #GFile for the given @path. - Free the returned object with g_object_unref(). - - - - - a string containing a relative or absolute path. - The string must be encoded in the glib filename encoding. - - - - - - Constructs a #GFile for a given URI. This operation never -fails, but the returned object might not support any I/O -operation if @uri is malformed or if the uri type is -not supported. - - - a new #GFile for the given @uri. - Free the returned object with g_object_unref(). - - - - - a UTF-8 string containing a URI - - - - - - Opens a file in the preferred directory for temporary files (as -returned by g_get_tmp_dir()) and returns a #GFile and -#GFileIOStream pointing to it. - -@tmpl should be a string in the GLib file name encoding -containing a sequence of six 'X' characters, and containing no -directory components. If it is %NULL, a default template is used. - -Unlike the other #GFile constructors, this will return %NULL if -a temporary file could not be created. - - - a new #GFile. - Free the returned object with g_object_unref(). - - - - - Template for the file - name, as in g_file_open_tmp(), or %NULL for a default template - - - - on return, a #GFileIOStream for the created file - - - - - - Constructs a #GFile with the given @parse_name (i.e. something -given by g_file_get_parse_name()). This operation never fails, -but the returned object might not support any I/O operation if -the @parse_name cannot be parsed. - - - a new #GFile. - - - - - a file name or path to be parsed - - - - - - Gets an output stream for appending data to the file. -If the file doesn't already exist it is created. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level that -is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -Some file systems don't allow all file names, and may return an -%G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the -%G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are -possible too, and depend on what kind of filesystem the file is on. - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously opens @file for appending. - -For more details, see g_file_append_to() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_append_to_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file append operation started with -g_file_append_to_async(). - - - a valid #GFileOutputStream - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - #GAsyncResult - - - - - - Copies the file @source to the location specified by @destination. -Can not handle recursive copies of directories. - -If the flag #G_FILE_COPY_OVERWRITE is specified an already -existing @destination file is overwritten. - -If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks -will be copied as symlinks, otherwise the target of the -@source symlink will be copied. - -If the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata -that is possible to copy is copied, not just the default subset (which, -for instance, does not include the owner, see #GFileInfo). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @progress_callback is not %NULL, then the operation can be monitored -by setting this to a #GFileProgressCallback function. -@progress_callback_data will be passed to this function. It is guaranteed -that this callback will be called after all data has been transferred with -the total number of bytes copied during the operation. - -If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error -is returned, independent on the status of the @destination. - -If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then -the error %G_IO_ERROR_EXISTS is returned. - -If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY -error is returned. If trying to overwrite a directory with a directory the -%G_IO_ERROR_WOULD_MERGE error is returned. - -If the source is a directory and the target does not exist, or -#G_FILE_COPY_OVERWRITE is specified and the target is a file, then the -%G_IO_ERROR_WOULD_RECURSE error is returned. - -If you are interested in copying the #GFile object itself (not the on-disk -file), see g_file_dup(). - - - %TRUE on success, %FALSE otherwise. - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with - progress information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - - - Copies the file @source to the location specified by @destination -asynchronously. For details of the behaviour, see g_file_copy(). - -If @progress_callback is not %NULL, then that function that will be called -just like in g_file_copy(). The callback will run in the default main context -of the thread calling g_file_copy_async() — the same context as @callback is -run in. - -When the operation is finished, @callback will be called. You can then call -g_file_copy_finish() to get the result of the operation. - - - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with progress - information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes copying the file started with g_file_copy_async(). - - - a %TRUE on success, %FALSE on error. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a new file and returns an output stream for writing to it. -The file must not already exist. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level -that is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If a file or directory with this name already exists the -%G_IO_ERROR_EXISTS error will be returned. Some file systems don't -allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME -error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will -be returned. Other errors are possible too, and depend on what kind -of filesystem the file is on. - - - a #GFileOutputStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a new file and returns an output stream -for writing to it. The file must not already exist. - -For more details, see g_file_create() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_create_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file create operation started with -g_file_create_async(). - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a new file and returns a stream for reading and -writing to it. The file must not already exist. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level -that is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If a file or directory with this name already exists, the -%G_IO_ERROR_EXISTS error will be returned. Some file systems don't -allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME -error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG -will be returned. Other errors are possible too, and depend on what -kind of filesystem the file is on. - -Note that in many non-local file cases read and write streams are -not supported, so make sure you really need to do read and write -streaming, rather than just opening for reading or writing. - - - a #GFileIOStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a new file and returns a stream -for reading and writing to it. The file must not already exist. - -For more details, see g_file_create_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_create_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file create operation started with -g_file_create_readwrite_async(). - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Deletes a file. If the @file is a directory, it will only be -deleted if it is empty. This has the same semantics as g_unlink(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously delete a file. If the @file is a directory, it will -only be deleted if it is empty. This has the same semantics as -g_unlink(). - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes deleting a file started with g_file_delete_async(). - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Duplicates a #GFile handle. This operation does not duplicate -the actual file or directory represented by the #GFile; see -g_file_copy() if attempting to copy a file. - -g_file_dup() is useful when a second handle is needed to the same underlying -file, for use in a separate thread (#GFile is not thread-safe). For use -within the same thread, use g_object_ref() to increment the existing object’s -reference count. - -This call does no blocking I/O. - - - a new #GFile that is a duplicate - of the given #GFile. - - - - - input #GFile - - - - - - Starts an asynchronous eject on a mountable. -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_eject_mountable_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - Use g_file_eject_mountable_with_operation() instead. - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an asynchronous eject operation started by -g_file_eject_mountable(). - Use g_file_eject_mountable_with_operation_finish() - instead. - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Starts an asynchronous eject on a mountable. -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_eject_mountable_with_operation_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an asynchronous eject operation started by -g_file_eject_mountable_with_operation(). - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Gets the requested information about the files in a directory. -The result is a #GFileEnumerator object that will give out -#GFileInfo objects for all the files in the directory. - -The @attributes value is a string that specifies the file -attributes that should be gathered. It is not an error if -it's not possible to read a particular requested attribute -from a file - it just won't be set. @attributes should -be a comma-separated list of attributes or attribute wildcards. -The wildcard "*" means all attributes, and a wildcard like -"standard::*" means all attributes in the standard namespace. -An example attribute query be "standard::*,owner::user". -The standard attributes are available as defines, like -#G_FILE_ATTRIBUTE_STANDARD_NAME. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY -error will be returned. Other errors are possible too. - - - A #GFileEnumerator if successful, - %NULL on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about the files -in a directory. The result is a #GFileEnumerator object that will -give out #GFileInfo objects for all the files in the directory. - -For more details, see g_file_enumerate_children() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_enumerate_children_finish() to get the result of -the operation. - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an async enumerate children operation. -See g_file_enumerate_children_async(). - - - a #GFileEnumerator or %NULL - if an error occurred. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Checks if the two given #GFiles refer to the same file. - -Note that two #GFiles that differ can still refer to the same -file on the filesystem due to various forms of filename -aliasing. - -This call does no blocking I/O. - - - %TRUE if @file1 and @file2 are equal. - - - - - the first #GFile - - - - the second #GFile - - - - - - Gets a #GMount for the #GFile. - -#GMount is returned only for user interesting locations, see -#GVolumeMonitor. If the #GFileIface for @file does not have a #mount, -@error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GMount where the @file is located - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the mount for the file. - -For more details, see g_file_find_enclosing_mount() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_find_enclosing_mount_finish() to -get the result of the operation. - - - - - - - a #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous find mount request. -See g_file_find_enclosing_mount_async(). - - - #GMount for given @file or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - Gets the child of @file for a given @display_name (i.e. a UTF-8 -version of the name). If this function fails, it returns %NULL -and @error will be set. This is very useful when constructing a -#GFile for a new file and the user entered the filename in the -user interface, for instance when you select a directory and -type a filename in the file selector. - -This call does no blocking I/O. - - - a #GFile to the specified child, or - %NULL if the display name couldn't be converted. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - string to a possible child - - - - - - Gets the parent directory for the @file. -If the @file represents the root directory of the -file system, then %NULL will be returned. - -This call does no blocking I/O. - - - a #GFile structure to the - parent of the given #GFile or %NULL if there is no parent. Free - the returned object with g_object_unref(). - - - - - input #GFile - - - - - - Gets the parse name of the @file. -A parse name is a UTF-8 string that describes the -file such that one can get the #GFile back using -g_file_parse_name(). - -This is generally used to show the #GFile as a nice -full-pathname kind of string in a user interface, -like in a location entry. - -For local files with names that can safely be converted -to UTF-8 the pathname is used, otherwise the IRI is used -(a form of URI that allows UTF-8 characters unescaped). - -This call does no blocking I/O. - - - a string containing the #GFile's parse name. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the URI for the @file. - -This call does no blocking I/O. - - - a string containing the #GFile's URI. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - Gets the URI scheme for a #GFile. -RFC 3986 decodes the scheme as: -|[ -URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] -]| -Common schemes include "file", "http", "ftp", etc. - -This call does no blocking I/O. - - - a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - Checks to see if a #GFile has a given URI scheme. - -This call does no blocking I/O. - - - %TRUE if #GFile's backend supports the - given URI scheme, %FALSE if URI scheme is %NULL, - not supported, or #GFile is invalid. - - - - - input #GFile - - - - a string containing a URI scheme - - - - - - Creates a hash value for a #GFile. - -This call does no blocking I/O. - - - 0 if @file is not a valid #GFile, otherwise an - integer that can be used as hash value for the #GFile. - This function is intended for easily hashing a #GFile to - add to a #GHashTable or similar data structure. - - - - - #gconstpointer to a #GFile - - - - - - Checks to see if a file is native to the platform. - -A native file is one expressed in the platform-native filename format, -e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, -as it might be on a locally mounted remote filesystem. - -On some systems non-native files may be available using the native -filesystem via a userspace filesystem (FUSE), in these cases this call -will return %FALSE, but g_file_get_path() will still return a native path. - -This call does no blocking I/O. - - - %TRUE if @file is native - - - - - input #GFile - - - - - - Creates a directory. Note that this will only create a child directory -of the immediate parent directory of the path or URI given by the #GFile. -To recursively create directories, see g_file_make_directory_with_parents(). -This function will fail if the parent directory does not exist, setting -@error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support -creating directories, this function will fail, setting @error to -%G_IO_ERROR_NOT_SUPPORTED. - -For a local #GFile the newly created directory will have the default -(current) ownership and permissions of the current process. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on successful creation, %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a directory. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous directory creation, started with -g_file_make_directory_async(). - - - %TRUE on successful directory creation, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a symbolic link named @file which contains the string -@symlink_value. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on the creation of a new symlink, %FALSE otherwise. - - - - - a #GFile with the name of the symlink to create - - - - a string with the path for the target - of the new symlink - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Recursively measures the disk usage of @file. - -This is essentially an analog of the 'du' command, but it also -reports the number of directories and non-directory files encountered -(including things like symbolic links). - -By default, errors are only reported against the toplevel file -itself. Errors found while recursing are silently ignored, unless -%G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. - -The returned size, @disk_usage, is in bytes and should be formatted -with g_format_size() in order to get something reasonable for showing -in a user interface. - -@progress_callback and @progress_data can be given to request -periodic progress updates while scanning. See the documentation for -#GFileMeasureProgressCallback for information about when and how the -callback will be invoked. - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - #GFileMeasureFlags - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - Recursively measures the disk usage of @file. - -This is the asynchronous version of g_file_measure_disk_usage(). See -there for more information. - - - - - - - a #GFile - - - - #GFileMeasureFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - a #GAsyncReadyCallback to call when complete - - - - the data to pass to callback function - - - - - - Collects the results from an earlier call to -g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for -more information. - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - the #GAsyncResult passed to your #GAsyncReadyCallback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - Obtains a directory monitor for the given file. -This may fail if directory monitoring is not supported. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -It does not make sense for @flags to contain -%G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to -directories. It is not possible to monitor all the files in a -directory for changes made via hard links; if you want to do this then -you must register individual watches with g_file_monitor(). - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Obtains a file monitor for the given file. If no file notification -mechanism exists, then regular polling of the file is used. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor -will also attempt to report changes made to the file via another -filename (ie, a hard link). Without this flag, you can only rely on -changes made through the filename contained in @file to be -reported. Using this flag may result in an increase in resource -usage, and may not have any effect depending on the #GFileMonitor -backend and/or filesystem type. - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Starts a @mount_operation, mounting the volume that contains -the file @location. - -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_mount_enclosing_volume_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a mount operation started by g_file_mount_enclosing_volume(). - - - %TRUE if successful. If an error has occurred, - this function will return %FALSE and set @error - appropriately if present. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Mounts a file of type G_FILE_TYPE_MOUNTABLE. -Using @mount_operation, you can request callbacks when, for instance, -passwords are needed during authentication. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a mount operation. See g_file_mount_mountable() for details. - -Finish an asynchronous mount operation that was started -with g_file_mount_mountable(). - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Tries to move the file or directory @source to the location specified -by @destination. If native move operations are supported then this is -used, otherwise a copy + delete fallback is used. The native -implementation may support moving directories (for instance on moves -inside the same filesystem), but the fallback code does not. - -If the flag #G_FILE_COPY_OVERWRITE is specified an already -existing @destination file is overwritten. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @progress_callback is not %NULL, then the operation can be monitored -by setting this to a #GFileProgressCallback function. -@progress_callback_data will be passed to this function. It is -guaranteed that this callback will be called after all data has been -transferred with the total number of bytes copied during the operation. - -If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND -error is returned, independent on the status of the @destination. - -If #G_FILE_COPY_OVERWRITE is not specified and the target exists, -then the error %G_IO_ERROR_EXISTS is returned. - -If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY -error is returned. If trying to overwrite a directory with a directory the -%G_IO_ERROR_WOULD_MERGE error is returned. - -If the source is a directory and the target does not exist, or -#G_FILE_COPY_OVERWRITE is specified and the target is a file, then -the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native -move operation isn't available). - - - %TRUE on successful move, %FALSE otherwise. - - - - - #GFile pointing to the source location - - - - #GFile pointing to the destination location - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - #GFileProgressCallback - function for updates - - - - gpointer to user data for - the callback function - - - - - - Opens an existing file for reading and writing. The result is -a #GFileIOStream that can be used to read and write the contents -of the file. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY -error will be returned. Other errors are possible too, and depend on -what kind of filesystem the file is on. Note that in many non-local -file cases read and write streams are not supported, so make sure you -really need to do read and write streaming, rather than just opening -for reading or writing. - - - #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to open - - - - a #GCancellable - - - - - - Asynchronously opens @file for reading and writing. - -For more details, see g_file_open_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_open_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file read operation started with -g_file_open_readwrite_async(). - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Polls a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a poll operation. See g_file_poll_mountable() for details. - -Finish an asynchronous poll operation that was polled -with g_file_poll_mountable(). - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Checks whether @file has the prefix specified by @prefix. - -In other words, if the names of initial elements of @file's -pathname match @prefix. Only full pathname elements are matched, -so a path like /foo is not considered a prefix of /foobar, only -of /foo/bar. - -A #GFile is not a prefix of itself. If you want to check for -equality, use g_file_equal(). - -This call does no I/O, as it works purely on names. As such it can -sometimes return %FALSE even if @file is inside a @prefix (from a -filesystem point of view), because the prefix of @file is an alias -of @prefix. - - - %TRUE if the @file's parent, grandparent, etc is @prefix, - %FALSE otherwise. - - - - - input #GFile - - - - input #GFile - - - - - - Similar to g_file_query_info(), but obtains information -about the filesystem the @file is on, rather than the file itself. -For instance the amount of space available and the type of -the filesystem. - -The @attributes value is a string that specifies the attributes -that should be gathered. It is not an error if it's not possible -to read a particular requested attribute from a file - it just -won't be set. @attributes should be a comma-separated list of -attributes or attribute wildcards. The wildcard "*" means all -attributes, and a wildcard like "filesystem::*" means all attributes -in the filesystem namespace. The standard namespace for filesystem -attributes is "filesystem". Common attributes of interest are -#G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem -in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), -and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. Other errors are possible too, and depend on what -kind of filesystem the file is on. - - - a #GFileInfo or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about the filesystem -that the specified @file is on. The result is a #GFileInfo object -that contains key-value attributes (such as type or size for the -file). - -For more details, see g_file_query_filesystem_info() which is the -synchronous version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_query_info_finish() to get the result of the -operation. - - - - - - - input #GFile - - - - an attribute query string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous filesystem info query. -See g_file_query_filesystem_info_async(). - - - #GFileInfo for given @file - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Gets the requested information about specified @file. -The result is a #GFileInfo object that contains key-value -attributes (such as the type or size of the file). - -The @attributes value is a string that specifies the file -attributes that should be gathered. It is not an error if -it's not possible to read a particular requested attribute -from a file - it just won't be set. @attributes should be a -comma-separated list of attributes or attribute wildcards. -The wildcard "*" means all attributes, and a wildcard like -"standard::*" means all attributes in the standard namespace. -An example attribute query be "standard::*,owner::user". -The standard attributes are available as defines, like -#G_FILE_ATTRIBUTE_STANDARD_NAME. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -For symlinks, normally the information about the target of the -symlink is returned, rather than information about the symlink -itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS -in @flags the information about the symlink itself will be returned. -Also, for symlinks that point to non-existing files the information -about the symlink itself will be returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be -returned. Other errors are possible too, and depend on what kind of -filesystem the file is on. - - - a #GFileInfo for the given @file, or %NULL - on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about specified @file. -The result is a #GFileInfo object that contains key-value attributes -(such as type or size for the file). - -For more details, see g_file_query_info() which is the synchronous -version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_query_info_finish() to get the result of the operation. - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file info query. -See g_file_query_info_async(). - - - #GFileInfo for given @file - or %NULL on error. Free the returned object with - g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Obtain the list of settable attributes for the file. - -Returns the type and full attribute name of all the attributes -that can be set on this file. This doesn't mean setting it will -always succeed though, you might get an access failure, or some -specific file may not support a specific attribute. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFileAttributeInfoList describing the settable attributes. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Obtain the list of attribute namespaces where new attributes -can be created by a user. An example of this is extended -attributes (in the "xattr" namespace). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFileAttributeInfoList describing the writable namespaces. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously opens @file for reading. - -For more details, see g_file_read() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_read_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file read operation started with -g_file_read_async(). - - - a #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Opens a file for reading. The result is a #GFileInputStream that -can be used to read the contents of the file. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be -returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY -error will be returned. Other errors are possible too, and depend -on what kind of filesystem the file is on. - - - #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to read - - - - a #GCancellable - - - - - - Returns an output stream for overwriting the file, possibly -creating a backup copy of the file first. If the file doesn't exist, -it will be created. - -This will try to replace the file in the safest way possible so -that any errors during the writing will not affect an already -existing copy of the file. For instance, for local files it -may write to a temporary file and then atomically rename over -the destination when the stream is closed. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level that -is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If you pass in a non-%NULL @etag value and @file already exists, then -this value is compared to the current entity tag of the file, and if -they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This -generally means that the file has been changed since you last read -it. You can get the new etag from g_file_output_stream_get_etag() -after you've finished writing and closed the #GFileOutputStream. When -you load a new file you can use g_file_input_stream_query_info() to -get the etag of the file. - -If @make_backup is %TRUE, this function will attempt to make a -backup of the current file before overwriting it. If this fails -a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you -want to replace anyway, try again with @make_backup set to %FALSE. - -If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will -be returned, and if the file is some other form of non-regular file -then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some -file systems don't allow all file names, and may return an -%G_IO_ERROR_INVALID_FILENAME error, and if the name is to long -%G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are -possible too, and depend on what kind of filesystem the file is on. - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously overwrites the file, replacing the contents, -possibly creating a backup copy of the file first. - -For more details, see g_file_replace() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_replace_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file replace operation started with -g_file_replace_async(). - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Returns an output stream for overwriting the file in readwrite mode, -possibly creating a backup copy of the file first. If the file doesn't -exist, it will be created. - -For details about the behaviour, see g_file_replace() which does the -same thing but returns an output stream only. - -Note that in many non-local file cases read and write streams are not -supported, so make sure you really need to do read and write streaming, -rather than just opening for reading or writing. - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously overwrites the file in read-write mode, -replacing the contents, possibly creating a backup copy -of the file first. - -For more details, see g_file_replace_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_replace_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file replace operation started with -g_file_replace_readwrite_async(). - - - a #GFileIOStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Resolves a relative path for @file to an absolute path. - -This call does no blocking I/O. - - - #GFile to the resolved path. - %NULL if @relative_path is %NULL or if @file is invalid. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a given relative path string - - - - - - Sets an attribute in the file with attribute name @attribute to @value_p. - -Some attributes can be unset by setting @type to -%G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the attribute was set, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - The type of the attribute - - - - a pointer to the value (or the pointer - itself if the type is a pointer type) - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sets the attributes of @file with @info. - -For more details, see g_file_set_attributes_from_info(), -which is the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_set_attributes_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a #GFileInfo - - - - a #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - Finishes setting an attribute started in g_file_set_attributes_async(). - - - %TRUE if the attributes were set correctly, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - a #GFileInfo - - - - - - Tries to set all attributes in the #GFileInfo on the target -values, not stopping on the first error. - -If there is any error during this operation then @error will -be set to the first error. Error on particular fields are flagged -by setting the "status" field in the attribute value to -%G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can -also detect further errors. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %FALSE if there was any error, %TRUE otherwise. - - - - - input #GFile - - - - a #GFileInfo - - - - #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Renames @file to the specified display name. - -The display name is converted from UTF-8 to the correct encoding -for the target filesystem if possible and the @file is renamed to this. - -If you want to implement a rename operation in the user interface the -edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the -initial value in the rename widget, and then the result after editing -should be passed to g_file_set_display_name(). - -On success the resulting converted filename is returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFile specifying what @file was renamed to, - or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sets the display name for a given #GFile. - -For more details, see g_file_set_display_name() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_set_display_name_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes setting a display name started with -g_file_set_display_name_async(). - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Starts a file of type #G_FILE_TYPE_MOUNTABLE. -Using @start_operation, you can request callbacks when, for instance, -passwords are needed during authentication. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a start operation. See g_file_start_mountable() for details. - -Finish an asynchronous start operation that was started -with g_file_start_mountable(). - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Stops a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_stop_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction. - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a stop operation, see g_file_stop_mountable() for details. - -Finish an asynchronous stop operation that was started -with g_file_stop_mountable(). - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Sends @file to the "Trashcan", if possible. This is similar to -deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the -%G_IO_ERROR_NOT_SUPPORTED error. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on successful trash, %FALSE otherwise. - - - - - #GFile to send to trash - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sends @file to the Trash location, if possible. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file trashing operation, started with -g_file_trash_async(). - - - %TRUE on successful trash, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_unmount_mountable_finish() to get -the result of the operation. - Use g_file_unmount_mountable_with_operation() instead. - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an unmount operation, see g_file_unmount_mountable() for details. - -Finish an asynchronous unmount operation that was started -with g_file_unmount_mountable(). - Use g_file_unmount_mountable_with_operation_finish() - instead. - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_unmount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an unmount operation, -see g_file_unmount_mountable_with_operation() for details. - -Finish an asynchronous unmount operation that was started -with g_file_unmount_mountable_with_operation(). - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Gets an output stream for appending data to the file. -If the file doesn't already exist it is created. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level that -is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -Some file systems don't allow all file names, and may return an -%G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the -%G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are -possible too, and depend on what kind of filesystem the file is on. - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously opens @file for appending. - -For more details, see g_file_append_to() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_append_to_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file append operation started with -g_file_append_to_async(). - - - a valid #GFileOutputStream - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - #GAsyncResult - - - - - - Copies the file @source to the location specified by @destination. -Can not handle recursive copies of directories. - -If the flag #G_FILE_COPY_OVERWRITE is specified an already -existing @destination file is overwritten. - -If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks -will be copied as symlinks, otherwise the target of the -@source symlink will be copied. - -If the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata -that is possible to copy is copied, not just the default subset (which, -for instance, does not include the owner, see #GFileInfo). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @progress_callback is not %NULL, then the operation can be monitored -by setting this to a #GFileProgressCallback function. -@progress_callback_data will be passed to this function. It is guaranteed -that this callback will be called after all data has been transferred with -the total number of bytes copied during the operation. - -If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error -is returned, independent on the status of the @destination. - -If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then -the error %G_IO_ERROR_EXISTS is returned. - -If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY -error is returned. If trying to overwrite a directory with a directory the -%G_IO_ERROR_WOULD_MERGE error is returned. - -If the source is a directory and the target does not exist, or -#G_FILE_COPY_OVERWRITE is specified and the target is a file, then the -%G_IO_ERROR_WOULD_RECURSE error is returned. - -If you are interested in copying the #GFile object itself (not the on-disk -file), see g_file_dup(). - - - %TRUE on success, %FALSE otherwise. - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with - progress information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - - - Copies the file @source to the location specified by @destination -asynchronously. For details of the behaviour, see g_file_copy(). - -If @progress_callback is not %NULL, then that function that will be called -just like in g_file_copy(). The callback will run in the default main context -of the thread calling g_file_copy_async() — the same context as @callback is -run in. - -When the operation is finished, @callback will be called. You can then call -g_file_copy_finish() to get the result of the operation. - - - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with progress - information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Copies the file attributes from @source to @destination. - -Normally only a subset of the file attributes are copied, -those that are copies in a normal file copy operation -(which for instance does not include e.g. owner). However -if #G_FILE_COPY_ALL_METADATA is specified in @flags, then -all the metadata that is possible to copy is copied. This -is useful when implementing move by copy + delete source. - - - %TRUE if the attributes were copied successfully, - %FALSE otherwise. - - - - - a #GFile with attributes - - - - a #GFile to copy attributes to - - - - a set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Finishes copying the file started with g_file_copy_async(). - - - a %TRUE on success, %FALSE on error. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a new file and returns an output stream for writing to it. -The file must not already exist. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level -that is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If a file or directory with this name already exists the -%G_IO_ERROR_EXISTS error will be returned. Some file systems don't -allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME -error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will -be returned. Other errors are possible too, and depend on what kind -of filesystem the file is on. - - - a #GFileOutputStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a new file and returns an output stream -for writing to it. The file must not already exist. - -For more details, see g_file_create() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_create_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file create operation started with -g_file_create_async(). - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a new file and returns a stream for reading and -writing to it. The file must not already exist. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level -that is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If a file or directory with this name already exists, the -%G_IO_ERROR_EXISTS error will be returned. Some file systems don't -allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME -error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG -will be returned. Other errors are possible too, and depend on what -kind of filesystem the file is on. - -Note that in many non-local file cases read and write streams are -not supported, so make sure you really need to do read and write -streaming, rather than just opening for reading or writing. - - - a #GFileIOStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a new file and returns a stream -for reading and writing to it. The file must not already exist. - -For more details, see g_file_create_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_create_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file create operation started with -g_file_create_readwrite_async(). - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Deletes a file. If the @file is a directory, it will only be -deleted if it is empty. This has the same semantics as g_unlink(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously delete a file. If the @file is a directory, it will -only be deleted if it is empty. This has the same semantics as -g_unlink(). - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes deleting a file started with g_file_delete_async(). - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Duplicates a #GFile handle. This operation does not duplicate -the actual file or directory represented by the #GFile; see -g_file_copy() if attempting to copy a file. - -g_file_dup() is useful when a second handle is needed to the same underlying -file, for use in a separate thread (#GFile is not thread-safe). For use -within the same thread, use g_object_ref() to increment the existing object’s -reference count. - -This call does no blocking I/O. - - - a new #GFile that is a duplicate - of the given #GFile. - - - - - input #GFile - - - - - - Starts an asynchronous eject on a mountable. -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_eject_mountable_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - Use g_file_eject_mountable_with_operation() instead. - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an asynchronous eject operation started by -g_file_eject_mountable(). - Use g_file_eject_mountable_with_operation_finish() - instead. - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Starts an asynchronous eject on a mountable. -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_eject_mountable_with_operation_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an asynchronous eject operation started by -g_file_eject_mountable_with_operation(). - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Gets the requested information about the files in a directory. -The result is a #GFileEnumerator object that will give out -#GFileInfo objects for all the files in the directory. - -The @attributes value is a string that specifies the file -attributes that should be gathered. It is not an error if -it's not possible to read a particular requested attribute -from a file - it just won't be set. @attributes should -be a comma-separated list of attributes or attribute wildcards. -The wildcard "*" means all attributes, and a wildcard like -"standard::*" means all attributes in the standard namespace. -An example attribute query be "standard::*,owner::user". -The standard attributes are available as defines, like -#G_FILE_ATTRIBUTE_STANDARD_NAME. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY -error will be returned. Other errors are possible too. - - - A #GFileEnumerator if successful, - %NULL on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about the files -in a directory. The result is a #GFileEnumerator object that will -give out #GFileInfo objects for all the files in the directory. - -For more details, see g_file_enumerate_children() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_enumerate_children_finish() to get the result of -the operation. - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an async enumerate children operation. -See g_file_enumerate_children_async(). - - - a #GFileEnumerator or %NULL - if an error occurred. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Checks if the two given #GFiles refer to the same file. - -Note that two #GFiles that differ can still refer to the same -file on the filesystem due to various forms of filename -aliasing. - -This call does no blocking I/O. - - - %TRUE if @file1 and @file2 are equal. - - - - - the first #GFile - - - - the second #GFile - - - - - - Gets a #GMount for the #GFile. - -#GMount is returned only for user interesting locations, see -#GVolumeMonitor. If the #GFileIface for @file does not have a #mount, -@error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GMount where the @file is located - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the mount for the file. - -For more details, see g_file_find_enclosing_mount() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_find_enclosing_mount_finish() to -get the result of the operation. - - - - - - - a #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous find mount request. -See g_file_find_enclosing_mount_async(). - - - #GMount for given @file or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a #GAsyncResult - - - - - - Gets the base name (the last component of the path) for a given #GFile. - -If called for the top level of a system (such as the filesystem root -or a uri like sftp://host/) it will return a single directory separator -(and on Windows, possibly a drive letter). - -The base name is a byte string (not UTF-8). It has no defined encoding -or rules other than it may not contain zero bytes. If you want to use -filenames in a user interface you should use the display name that you -can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME -attribute with g_file_query_info(). - -This call does no blocking I/O. - - - string containing the #GFile's - base name, or %NULL if given #GFile is invalid. The returned string - should be freed with g_free() when no longer needed. - - - - - input #GFile - - - - - - Gets a child of @file with basename equal to @name. - -Note that the file with that specific name might not exist, but -you can still have a #GFile that points to it. You can use this -for instance to create that file. - -This call does no blocking I/O. - - - a #GFile to a child specified by @name. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - string containing the child's basename - - - - - - Gets the child of @file for a given @display_name (i.e. a UTF-8 -version of the name). If this function fails, it returns %NULL -and @error will be set. This is very useful when constructing a -#GFile for a new file and the user entered the filename in the -user interface, for instance when you select a directory and -type a filename in the file selector. - -This call does no blocking I/O. - - - a #GFile to the specified child, or - %NULL if the display name couldn't be converted. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - string to a possible child - - - - - - Gets the parent directory for the @file. -If the @file represents the root directory of the -file system, then %NULL will be returned. - -This call does no blocking I/O. - - - a #GFile structure to the - parent of the given #GFile or %NULL if there is no parent. Free - the returned object with g_object_unref(). - - - - - input #GFile - - - - - - Gets the parse name of the @file. -A parse name is a UTF-8 string that describes the -file such that one can get the #GFile back using -g_file_parse_name(). - -This is generally used to show the #GFile as a nice -full-pathname kind of string in a user interface, -like in a location entry. - -For local files with names that can safely be converted -to UTF-8 the pathname is used, otherwise the IRI is used -(a form of URI that allows UTF-8 characters unescaped). - -This call does no blocking I/O. - - - a string containing the #GFile's parse name. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - Gets the local pathname for #GFile, if one exists. If non-%NULL, this is -guaranteed to be an absolute, canonical path. It might contain symlinks. - -This call does no blocking I/O. - - - string containing the #GFile's path, - or %NULL if no such path exists. The returned string should be freed - with g_free() when no longer needed. - - - - - input #GFile - - - - - - Gets the path for @descendant relative to @parent. - -This call does no blocking I/O. - - - string with the relative path from - @descendant to @parent, or %NULL if @descendant doesn't have @parent as - prefix. The returned string should be freed with g_free() when - no longer needed. - - - - - input #GFile - - - - input #GFile - - - - - - Gets the URI for the @file. - -This call does no blocking I/O. - - - a string containing the #GFile's URI. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - Gets the URI scheme for a #GFile. -RFC 3986 decodes the scheme as: -|[ -URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] -]| -Common schemes include "file", "http", "ftp", etc. - -This call does no blocking I/O. - - - a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - Checks if @file has a parent, and optionally, if it is @parent. - -If @parent is %NULL then this function returns %TRUE if @file has any -parent at all. If @parent is non-%NULL then %TRUE is only returned -if @file is an immediate child of @parent. - - - %TRUE if @file is an immediate child of @parent (or any parent in - the case that @parent is %NULL). - - - - - input #GFile - - - - the parent to check for, or %NULL - - - - - - Checks whether @file has the prefix specified by @prefix. - -In other words, if the names of initial elements of @file's -pathname match @prefix. Only full pathname elements are matched, -so a path like /foo is not considered a prefix of /foobar, only -of /foo/bar. - -A #GFile is not a prefix of itself. If you want to check for -equality, use g_file_equal(). - -This call does no I/O, as it works purely on names. As such it can -sometimes return %FALSE even if @file is inside a @prefix (from a -filesystem point of view), because the prefix of @file is an alias -of @prefix. - - - %TRUE if the @file's parent, grandparent, etc is @prefix, - %FALSE otherwise. - - - - - input #GFile - - - - input #GFile - - - - - - Checks to see if a #GFile has a given URI scheme. - -This call does no blocking I/O. - - - %TRUE if #GFile's backend supports the - given URI scheme, %FALSE if URI scheme is %NULL, - not supported, or #GFile is invalid. - - - - - input #GFile - - - - a string containing a URI scheme - - - - - - Creates a hash value for a #GFile. - -This call does no blocking I/O. - - - 0 if @file is not a valid #GFile, otherwise an - integer that can be used as hash value for the #GFile. - This function is intended for easily hashing a #GFile to - add to a #GHashTable or similar data structure. - - - - - #gconstpointer to a #GFile - - - - - - Checks to see if a file is native to the platform. - -A native file is one expressed in the platform-native filename format, -e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, -as it might be on a locally mounted remote filesystem. - -On some systems non-native files may be available using the native -filesystem via a userspace filesystem (FUSE), in these cases this call -will return %FALSE, but g_file_get_path() will still return a native path. - -This call does no blocking I/O. - - - %TRUE if @file is native - - - - - input #GFile - - - - - - Loads the contents of @file and returns it as #GBytes. - -If @file is a resource:// based URI, the resulting bytes will reference the -embedded resource instead of a copy. Otherwise, this is equivalent to calling -g_file_load_contents() and g_bytes_new_take(). - -For resources, @etag_out will be set to %NULL. - -The data contained in the resulting #GBytes is always zero-terminated, but -this is not included in the #GBytes length. The resulting #GBytes should be -freed with g_bytes_unref() when no longer in use. - - - a #GBytes or %NULL and @error is set - - - - - a #GFile - - - - a #GCancellable or %NULL - - - - a location to place the current - entity tag for the file, or %NULL if the entity tag is not needed - - - - - - Asynchronously loads the contents of @file as #GBytes. - -If @file is a resource:// based URI, the resulting bytes will reference the -embedded resource instead of a copy. Otherwise, this is equivalent to calling -g_file_load_contents_async() and g_bytes_new_take(). - -@callback should call g_file_load_bytes_finish() to get the result of this -asynchronous operation. - -See g_file_load_bytes() for more information. - - - - - - - a #GFile - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Completes an asynchronous request to g_file_load_bytes_async(). - -For resources, @etag_out will be set to %NULL. - -The data contained in the resulting #GBytes is always zero-terminated, but -this is not included in the #GBytes length. The resulting #GBytes should be -freed with g_bytes_unref() when no longer in use. - -See g_file_load_bytes() for more information. - - - a #GBytes or %NULL and @error is set - - - - - a #GFile - - - - a #GAsyncResult provided to the callback - - - - a location to place the current - entity tag for the file, or %NULL if the entity tag is not needed - - - - - - Loads the content of the file into memory. The data is always -zero-terminated, but this is not included in the resultant @length. -The returned @contents should be freed with g_free() when no longer -needed. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @file's contents were successfully loaded. - %FALSE if there were errors. - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a location to place the contents of the file - - - - - - a location to place the length of the contents of the file, - or %NULL if the length is not needed - - - - a location to place the current entity tag for the file, - or %NULL if the entity tag is not needed - - - - - - Starts an asynchronous load of the @file's contents. - -For more details, see g_file_load_contents() which is -the synchronous version of this call. - -When the load operation has completed, @callback will be called -with @user data. To finish the operation, call -g_file_load_contents_finish() with the #GAsyncResult returned by -the @callback. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous load of the @file's contents. -The contents are placed in @contents, and @length is set to the -size of the @contents string. The @contents should be freed with -g_free() when no longer needed. If @etag_out is present, it will be -set to the new entity tag for the @file. - - - %TRUE if the load was successful. If %FALSE and @error is - present, it will be set appropriately. - - - - - input #GFile - - - - a #GAsyncResult - - - - a location to place the contents of the file - - - - - - a location to place the length of the contents of the file, - or %NULL if the length is not needed - - - - a location to place the current entity tag for the file, - or %NULL if the entity tag is not needed - - - - - - Reads the partial contents of a file. A #GFileReadMoreCallback should -be used to stop reading from the file when appropriate, else this -function will behave exactly as g_file_load_contents_async(). This -operation can be finished by g_file_load_partial_contents_finish(). - -Users of this function should be aware that @user_data is passed to -both the @read_more_callback and the @callback. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a - #GFileReadMoreCallback to receive partial data - and to specify whether further data should be read - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to the callback functions - - - - - - Finishes an asynchronous partial load operation that was started -with g_file_load_partial_contents_async(). The data is always -zero-terminated, but this is not included in the resultant @length. -The returned @contents should be freed with g_free() when no longer -needed. - - - %TRUE if the load was successful. If %FALSE and @error is - present, it will be set appropriately. - - - - - input #GFile - - - - a #GAsyncResult - - - - a location to place the contents of the file - - - - - - a location to place the length of the contents of the file, - or %NULL if the length is not needed - - - - a location to place the current entity tag for the file, - or %NULL if the entity tag is not needed - - - - - - Creates a directory. Note that this will only create a child directory -of the immediate parent directory of the path or URI given by the #GFile. -To recursively create directories, see g_file_make_directory_with_parents(). -This function will fail if the parent directory does not exist, setting -@error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support -creating directories, this function will fail, setting @error to -%G_IO_ERROR_NOT_SUPPORTED. - -For a local #GFile the newly created directory will have the default -(current) ownership and permissions of the current process. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on successful creation, %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously creates a directory. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous directory creation, started with -g_file_make_directory_async(). - - - %TRUE on successful directory creation, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Creates a directory and any parent directories that may not -exist similar to 'mkdir -p'. If the file system does not support -creating directories, this function will fail, setting @error to -%G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, -this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike -the similar g_mkdir_with_parents(). - -For a local #GFile the newly created directories will have the default -(current) ownership and permissions of the current process. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if all directories have been successfully created, %FALSE -otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Creates a symbolic link named @file which contains the string -@symlink_value. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on the creation of a new symlink, %FALSE otherwise. - - - - - a #GFile with the name of the symlink to create - - - - a string with the path for the target - of the new symlink - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Recursively measures the disk usage of @file. - -This is essentially an analog of the 'du' command, but it also -reports the number of directories and non-directory files encountered -(including things like symbolic links). - -By default, errors are only reported against the toplevel file -itself. Errors found while recursing are silently ignored, unless -%G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. - -The returned size, @disk_usage, is in bytes and should be formatted -with g_format_size() in order to get something reasonable for showing -in a user interface. - -@progress_callback and @progress_data can be given to request -periodic progress updates while scanning. See the documentation for -#GFileMeasureProgressCallback for information about when and how the -callback will be invoked. - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - #GFileMeasureFlags - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - Recursively measures the disk usage of @file. - -This is the asynchronous version of g_file_measure_disk_usage(). See -there for more information. - - - - - - - a #GFile - - - - #GFileMeasureFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - a #GAsyncReadyCallback to call when complete - - - - the data to pass to callback function - - - - - - Collects the results from an earlier call to -g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for -more information. - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - the #GAsyncResult passed to your #GAsyncReadyCallback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - Obtains a file or directory monitor for the given file, -depending on the type of the file. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Obtains a directory monitor for the given file. -This may fail if directory monitoring is not supported. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -It does not make sense for @flags to contain -%G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to -directories. It is not possible to monitor all the files in a -directory for changes made via hard links; if you want to do this then -you must register individual watches with g_file_monitor(). - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Obtains a file monitor for the given file. If no file notification -mechanism exists, then regular polling of the file is used. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor -will also attempt to report changes made to the file via another -filename (ie, a hard link). Without this flag, you can only rely on -changes made through the filename contained in @file to be -reported. Using this flag may result in an increase in resource -usage, and may not have any effect depending on the #GFileMonitor -backend and/or filesystem type. - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Starts a @mount_operation, mounting the volume that contains -the file @location. - -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_mount_enclosing_volume_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a mount operation started by g_file_mount_enclosing_volume(). - - - %TRUE if successful. If an error has occurred, - this function will return %FALSE and set @error - appropriately if present. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Mounts a file of type G_FILE_TYPE_MOUNTABLE. -Using @mount_operation, you can request callbacks when, for instance, -passwords are needed during authentication. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a mount operation. See g_file_mount_mountable() for details. - -Finish an asynchronous mount operation that was started -with g_file_mount_mountable(). - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Tries to move the file or directory @source to the location specified -by @destination. If native move operations are supported then this is -used, otherwise a copy + delete fallback is used. The native -implementation may support moving directories (for instance on moves -inside the same filesystem), but the fallback code does not. - -If the flag #G_FILE_COPY_OVERWRITE is specified an already -existing @destination file is overwritten. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @progress_callback is not %NULL, then the operation can be monitored -by setting this to a #GFileProgressCallback function. -@progress_callback_data will be passed to this function. It is -guaranteed that this callback will be called after all data has been -transferred with the total number of bytes copied during the operation. - -If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND -error is returned, independent on the status of the @destination. - -If #G_FILE_COPY_OVERWRITE is not specified and the target exists, -then the error %G_IO_ERROR_EXISTS is returned. - -If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY -error is returned. If trying to overwrite a directory with a directory the -%G_IO_ERROR_WOULD_MERGE error is returned. - -If the source is a directory and the target does not exist, or -#G_FILE_COPY_OVERWRITE is specified and the target is a file, then -the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native -move operation isn't available). - - - %TRUE on successful move, %FALSE otherwise. - - - - - #GFile pointing to the source location - - - - #GFile pointing to the destination location - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - #GFileProgressCallback - function for updates - - - - gpointer to user data for - the callback function - - - - - - Opens an existing file for reading and writing. The result is -a #GFileIOStream that can be used to read and write the contents -of the file. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY -error will be returned. Other errors are possible too, and depend on -what kind of filesystem the file is on. Note that in many non-local -file cases read and write streams are not supported, so make sure you -really need to do read and write streaming, rather than just opening -for reading or writing. - - - #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to open - - - - a #GCancellable - - - - - - Asynchronously opens @file for reading and writing. - -For more details, see g_file_open_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_open_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file read operation started with -g_file_open_readwrite_async(). - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Exactly like g_file_get_path(), but caches the result via -g_object_set_qdata_full(). This is useful for example in C -applications which mix `g_file_*` APIs with native ones. It -also avoids an extra duplicated string when possible, so will be -generally more efficient. - -This call does no blocking I/O. - - - string containing the #GFile's path, - or %NULL if no such path exists. The returned string is owned by @file. - - - - - input #GFile - - - - - - Polls a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a poll operation. See g_file_poll_mountable() for details. - -Finish an asynchronous poll operation that was polled -with g_file_poll_mountable(). - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Returns the #GAppInfo that is registered as the default -application to handle the file specified by @file. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GAppInfo if the handle was found, - %NULL if there were errors. - When you are done with it, release it with g_object_unref() - - - - - a #GFile to open - - - - optional #GCancellable object, %NULL to ignore - - - - - - Async version of g_file_query_default_handler(). - - - - - - - a #GFile to open - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - Finishes a g_file_query_default_handler_async() operation. - - - a #GAppInfo if the handle was found, - %NULL if there were errors. - When you are done with it, release it with g_object_unref() - - - - - a #GFile to open - - - - a #GAsyncResult - - - - - - Utility function to check if a particular file exists. This is -implemented using g_file_query_info() and as such does blocking I/O. - -Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) -and then execute something based on the outcome of that, because the -file might have been created or removed in between the operations. The -general approach to handling that is to not check, but just do the -operation and handle the errors as they come. - -As an example of race-free checking, take the case of reading a file, -and if it doesn't exist, creating it. There are two racy versions: read -it, and on error create it; and: check if it exists, if not create it. -These can both result in two processes creating the file (with perhaps -a partially written file as the result). The correct approach is to -always try to create the file with g_file_create() which will either -atomically create the file or fail with a %G_IO_ERROR_EXISTS error. - -However, in many cases an existence check is useful in a user interface, -for instance to make a menu item sensitive/insensitive, so that you don't -have to fool users that something is possible and then just show an error -dialog. If you do this, you should make sure to also handle the errors -that can happen due to races when you execute the operation. - - - %TRUE if the file exists (and can be detected without error), - %FALSE otherwise (or if cancelled). - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Utility function to inspect the #GFileType of a file. This is -implemented using g_file_query_info() and as such does blocking I/O. - -The primary use case of this method is to check if a file is -a regular file, directory, or symlink. - - - The #GFileType of the file and #G_FILE_TYPE_UNKNOWN - if the file does not exist - - - - - input #GFile - - - - a set of #GFileQueryInfoFlags passed to g_file_query_info() - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Similar to g_file_query_info(), but obtains information -about the filesystem the @file is on, rather than the file itself. -For instance the amount of space available and the type of -the filesystem. - -The @attributes value is a string that specifies the attributes -that should be gathered. It is not an error if it's not possible -to read a particular requested attribute from a file - it just -won't be set. @attributes should be a comma-separated list of -attributes or attribute wildcards. The wildcard "*" means all -attributes, and a wildcard like "filesystem::*" means all attributes -in the filesystem namespace. The standard namespace for filesystem -attributes is "filesystem". Common attributes of interest are -#G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem -in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), -and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will -be returned. Other errors are possible too, and depend on what -kind of filesystem the file is on. - - - a #GFileInfo or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about the filesystem -that the specified @file is on. The result is a #GFileInfo object -that contains key-value attributes (such as type or size for the -file). - -For more details, see g_file_query_filesystem_info() which is the -synchronous version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_query_info_finish() to get the result of the -operation. - - - - - - - input #GFile - - - - an attribute query string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous filesystem info query. -See g_file_query_filesystem_info_async(). - - - #GFileInfo for given @file - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Gets the requested information about specified @file. -The result is a #GFileInfo object that contains key-value -attributes (such as the type or size of the file). - -The @attributes value is a string that specifies the file -attributes that should be gathered. It is not an error if -it's not possible to read a particular requested attribute -from a file - it just won't be set. @attributes should be a -comma-separated list of attributes or attribute wildcards. -The wildcard "*" means all attributes, and a wildcard like -"standard::*" means all attributes in the standard namespace. -An example attribute query be "standard::*,owner::user". -The standard attributes are available as defines, like -#G_FILE_ATTRIBUTE_STANDARD_NAME. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -For symlinks, normally the information about the target of the -symlink is returned, rather than information about the symlink -itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS -in @flags the information about the symlink itself will be returned. -Also, for symlinks that point to non-existing files the information -about the symlink itself will be returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be -returned. Other errors are possible too, and depend on what kind of -filesystem the file is on. - - - a #GFileInfo for the given @file, or %NULL - on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously gets the requested information about specified @file. -The result is a #GFileInfo object that contains key-value attributes -(such as type or size for the file). - -For more details, see g_file_query_info() which is the synchronous -version of this call. - -When the operation is finished, @callback will be called. You can -then call g_file_query_info_finish() to get the result of the operation. - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file info query. -See g_file_query_info_async(). - - - #GFileInfo for given @file - or %NULL on error. Free the returned object with - g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Obtain the list of settable attributes for the file. - -Returns the type and full attribute name of all the attributes -that can be set on this file. This doesn't mean setting it will -always succeed though, you might get an access failure, or some -specific file may not support a specific attribute. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFileAttributeInfoList describing the settable attributes. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Obtain the list of attribute namespaces where new attributes -can be created by a user. An example of this is extended -attributes (in the "xattr" namespace). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFileAttributeInfoList describing the writable namespaces. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Opens a file for reading. The result is a #GFileInputStream that -can be used to read the contents of the file. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be -returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY -error will be returned. Other errors are possible too, and depend -on what kind of filesystem the file is on. - - - #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to read - - - - a #GCancellable - - - - - - Asynchronously opens @file for reading. - -For more details, see g_file_read() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_read_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file read operation started with -g_file_read_async(). - - - a #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Returns an output stream for overwriting the file, possibly -creating a backup copy of the file first. If the file doesn't exist, -it will be created. - -This will try to replace the file in the safest way possible so -that any errors during the writing will not affect an already -existing copy of the file. For instance, for local files it -may write to a temporary file and then atomically rename over -the destination when the stream is closed. - -By default files created are generally readable by everyone, -but if you pass #G_FILE_CREATE_PRIVATE in @flags the file -will be made readable only to the current user, to the level that -is supported on the target filesystem. - -If @cancellable is not %NULL, then the operation can be cancelled -by triggering the cancellable object from another thread. If the -operation was cancelled, the error %G_IO_ERROR_CANCELLED will be -returned. - -If you pass in a non-%NULL @etag value and @file already exists, then -this value is compared to the current entity tag of the file, and if -they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This -generally means that the file has been changed since you last read -it. You can get the new etag from g_file_output_stream_get_etag() -after you've finished writing and closed the #GFileOutputStream. When -you load a new file you can use g_file_input_stream_query_info() to -get the etag of the file. - -If @make_backup is %TRUE, this function will attempt to make a -backup of the current file before overwriting it. If this fails -a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you -want to replace anyway, try again with @make_backup set to %FALSE. - -If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will -be returned, and if the file is some other form of non-regular file -then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some -file systems don't allow all file names, and may return an -%G_IO_ERROR_INVALID_FILENAME error, and if the name is to long -%G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are -possible too, and depend on what kind of filesystem the file is on. - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously overwrites the file, replacing the contents, -possibly creating a backup copy of the file first. - -For more details, see g_file_replace() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_replace_finish() to get the result -of the operation. - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Replaces the contents of @file with @contents of @length bytes. - -If @etag is specified (not %NULL), any existing file must have that etag, -or the error %G_IO_ERROR_WRONG_ETAG will be returned. - -If @make_backup is %TRUE, this function will attempt to make a backup -of @file. Internally, it uses g_file_replace(), so will try to replace the -file contents in the safest way possible. For example, atomic renames are -used when replacing local files’ contents. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -The returned @new_etag can be used to verify that the file hasn't -changed the next time it is saved over. - - - %TRUE if successful. If an error has occurred, this function - will return %FALSE and set @error appropriately if present. - - - - - input #GFile - - - - a string containing the new contents for @file - - - - - - the length of @contents in bytes - - - - the old [entity-tag][gfile-etag] for the document, - or %NULL - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - a location to a new [entity tag][gfile-etag] - for the document. This should be freed with g_free() when no longer - needed, or %NULL - - - - optional #GCancellable object, %NULL to ignore - - - - - - Starts an asynchronous replacement of @file with the given -@contents of @length bytes. @etag will replace the document's -current entity tag. - -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_replace_contents_finish(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -If @make_backup is %TRUE, this function will attempt to -make a backup of @file. - -Note that no copy of @contents will be made, so it must stay valid -until @callback is called. See g_file_replace_contents_bytes_async() -for a #GBytes version that will automatically hold a reference to the -contents (without copying) for the duration of the call. - - - - - - - input #GFile - - - - string of contents to replace the file with - - - - - - the length of @contents in bytes - - - - a new [entity tag][gfile-etag] for the @file, or %NULL - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Same as g_file_replace_contents_async() but takes a #GBytes input instead. -This function will keep a ref on @contents until the operation is done. -Unlike g_file_replace_contents_async() this allows forgetting about the -content without waiting for the callback. - -When this operation has completed, @callback will be called with -@user_user data, and the operation can be finalized with -g_file_replace_contents_finish(). - - - - - - - input #GFile - - - - a #GBytes - - - - a new [entity tag][gfile-etag] for the @file, or %NULL - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous replace of the given @file. See -g_file_replace_contents_async(). Sets @new_etag to the new entity -tag for the document, if present. - - - %TRUE on success, %FALSE on failure. - - - - - input #GFile - - - - a #GAsyncResult - - - - a location of a new [entity tag][gfile-etag] - for the document. This should be freed with g_free() when it is no - longer needed, or %NULL - - - - - - Finishes an asynchronous file replace operation started with -g_file_replace_async(). - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Returns an output stream for overwriting the file in readwrite mode, -possibly creating a backup copy of the file first. If the file doesn't -exist, it will be created. - -For details about the behaviour, see g_file_replace() which does the -same thing but returns an output stream only. - -Note that in many non-local file cases read and write streams are not -supported, so make sure you really need to do read and write streaming, -rather than just opening for reading or writing. - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously overwrites the file in read-write mode, -replacing the contents, possibly creating a backup copy -of the file first. - -For more details, see g_file_replace_readwrite() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_replace_readwrite_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file replace operation started with -g_file_replace_readwrite_async(). - - - a #GFileIOStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Resolves a relative path for @file to an absolute path. - -This call does no blocking I/O. - - - #GFile to the resolved path. - %NULL if @relative_path is %NULL or if @file is invalid. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a given relative path string - - - - - - Sets an attribute in the file with attribute name @attribute to @value_p. - -Some attributes can be unset by setting @type to -%G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the attribute was set, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - The type of the attribute - - - - a pointer to the value (or the pointer - itself if the type is a pointer type) - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. -If @attribute is of a different type, this operation will fail, -returning %FALSE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set to @value - in the @file, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a string containing the attribute's new value - - - - a #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. -If @attribute is of a different type, this operation will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set to @value - in the @file, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a #gint32 containing the attribute's new value - - - - a #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. -If @attribute is of a different type, this operation will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a #guint64 containing the attribute's new value - - - - a #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. -If @attribute is of a different type, this operation will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a string containing the attribute's value - - - - #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. -If @attribute is of a different type, this operation will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set to @value - in the @file, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a #guint32 containing the attribute's new value - - - - a #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. -If @attribute is of a different type, this operation will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if the @attribute was successfully set to @value - in the @file, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - a #guint64 containing the attribute's new value - - - - a #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sets the attributes of @file with @info. - -For more details, see g_file_set_attributes_from_info(), -which is the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_set_attributes_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a #GFileInfo - - - - a #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - Finishes setting an attribute started in g_file_set_attributes_async(). - - - %TRUE if the attributes were set correctly, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - a #GFileInfo - - - - - - Tries to set all attributes in the #GFileInfo on the target -values, not stopping on the first error. - -If there is any error during this operation then @error will -be set to the first error. Error on particular fields are flagged -by setting the "status" field in the attribute value to -%G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can -also detect further errors. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %FALSE if there was any error, %TRUE otherwise. - - - - - input #GFile - - - - a #GFileInfo - - - - #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Renames @file to the specified display name. - -The display name is converted from UTF-8 to the correct encoding -for the target filesystem if possible and the @file is renamed to this. - -If you want to implement a rename operation in the user interface the -edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the -initial value in the rename widget, and then the result after editing -should be passed to g_file_set_display_name(). - -On success the resulting converted filename is returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GFile specifying what @file was renamed to, - or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sets the display name for a given #GFile. - -For more details, see g_file_set_display_name() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. -You can then call g_file_set_display_name_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - a string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes setting a display name started with -g_file_set_display_name_async(). - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Starts a file of type #G_FILE_TYPE_MOUNTABLE. -Using @start_operation, you can request callbacks when, for instance, -passwords are needed during authentication. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_mount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a start operation. See g_file_start_mountable() for details. - -Finish an asynchronous start operation that was started -with g_file_start_mountable(). - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Stops a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_stop_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction. - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes a stop operation, see g_file_stop_mountable() for details. - -Finish an asynchronous stop operation that was started -with g_file_stop_mountable(). - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Checks if @file supports -[thread-default contexts][g-main-context-push-thread-default-context]. -If this returns %FALSE, you cannot perform asynchronous operations on -@file in a thread that has a thread-default context. - - - Whether or not @file supports thread-default contexts. - - - - - a #GFile - - - - - - Sends @file to the "Trashcan", if possible. This is similar to -deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the -%G_IO_ERROR_NOT_SUPPORTED error. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on successful trash, %FALSE otherwise. - - - - - #GFile to send to trash - - - - optional #GCancellable object, - %NULL to ignore - - - - - - Asynchronously sends @file to the Trash location, if possible. - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous file trashing operation, started with -g_file_trash_async(). - - - %TRUE on successful trash, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_unmount_mountable_finish() to get -the result of the operation. - Use g_file_unmount_mountable_with_operation() instead. - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an unmount operation, see g_file_unmount_mountable() for details. - -Finish an asynchronous unmount operation that was started -with g_file_unmount_mountable(). - Use g_file_unmount_mountable_with_operation_finish() - instead. - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - -When the operation is finished, @callback will be called. -You can then call g_file_unmount_mountable_finish() to get -the result of the operation. - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - Finishes an unmount operation, -see g_file_unmount_mountable_with_operation() for details. - -Finish an asynchronous unmount operation that was started -with g_file_unmount_mountable_with_operation(). - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - Information about a specific attribute. - - - the name of the attribute. - - - - the #GFileAttributeType type of the attribute. - - - - a set of #GFileAttributeInfoFlags. - - - - - Flags specifying the behaviour of an attribute. - - no flags set. - - - copy the attribute values when the file is copied. - - - copy the attribute values when the file is moved. - - - - Acts as a lightweight registry for possible valid file attributes. -The registry stores Key-Value pair formats as #GFileAttributeInfos. - - - an array of #GFileAttributeInfos. - - - - the number of values in the array. - - - - Creates a new file attribute info list. - - - a #GFileAttributeInfoList. - - - - - Adds a new attribute with @name to the @list, setting -its @type and @flags. - - - - - - - a #GFileAttributeInfoList. - - - - the name of the attribute to add. - - - - the #GFileAttributeType for the attribute. - - - - #GFileAttributeInfoFlags for the attribute. - - - - - - Makes a duplicate of a file attribute info list. - - - a copy of the given @list. - - - - - a #GFileAttributeInfoList to duplicate. - - - - - - Gets the file attribute with the name @name from @list. - - - a #GFileAttributeInfo for the @name, or %NULL if an -attribute isn't found. - - - - - a #GFileAttributeInfoList. - - - - the name of the attribute to look up. - - - - - - References a file attribute info list. - - - #GFileAttributeInfoList or %NULL on error. - - - - - a #GFileAttributeInfoList to reference. - - - - - - Removes a reference from the given @list. If the reference count -falls to zero, the @list is deleted. - - - - - - - The #GFileAttributeInfoList to unreference. - - - - - - - Determines if a string matches a file attribute. - - - Creates a new file attribute matcher, which matches attributes -against a given string. #GFileAttributeMatchers are reference -counted structures, and are created with a reference count of 1. If -the number of references falls to 0, the #GFileAttributeMatcher is -automatically destroyed. - -The @attributes string should be formatted with specific keys separated -from namespaces with a double colon. Several "namespace::key" strings may be -concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). -The wildcard "*" may be used to match all keys and namespaces, or -"namespace::*" will match all keys in a given namespace. - -## Examples of file attribute matcher strings and results - -- `"*"`: matches all attributes. -- `"standard::is-hidden"`: matches only the key is-hidden in the - standard namespace. -- `"standard::type,unix::*"`: matches the type key in the standard - namespace and all keys in the unix namespace. - - - a #GFileAttributeMatcher - - - - - an attribute string to match. - - - - - - Checks if the matcher will match all of the keys in a given namespace. -This will always return %TRUE if a wildcard character is in use (e.g. if -matcher was created with "standard::*" and @ns is "standard", or if matcher was created -using "*" and namespace is anything.) - -TODO: this is awkwardly worded. - - - %TRUE if the matcher matches all of the entries -in the given @ns, %FALSE otherwise. - - - - - a #GFileAttributeMatcher. - - - - a string containing a file attribute namespace. - - - - - - Gets the next matched attribute from a #GFileAttributeMatcher. - - - a string containing the next attribute or %NULL if -no more attribute exist. - - - - - a #GFileAttributeMatcher. - - - - - - Checks if an attribute will be matched by an attribute matcher. If -the matcher was created with the "*" matching string, this function -will always return %TRUE. - - - %TRUE if @attribute matches @matcher. %FALSE otherwise. - - - - - a #GFileAttributeMatcher. - - - - a file attribute key. - - - - - - Checks if a attribute matcher only matches a given attribute. Always -returns %FALSE if "*" was used when creating the matcher. - - - %TRUE if the matcher only matches @attribute. %FALSE otherwise. - - - - - a #GFileAttributeMatcher. - - - - a file attribute key. - - - - - - References a file attribute matcher. - - - a #GFileAttributeMatcher. - - - - - a #GFileAttributeMatcher. - - - - - - Subtracts all attributes of @subtract from @matcher and returns -a matcher that supports those attributes. - -Note that currently it is not possible to remove a single -attribute when the @matcher matches the whole namespace - or remove -a namespace or attribute when the matcher matches everything. This -is a limitation of the current implementation, but may be fixed -in the future. - - - A file attribute matcher matching all attributes of - @matcher that are not matched by @subtract - - - - - Matcher to subtract from - - - - The matcher to subtract - - - - - - Prints what the matcher is matching against. The format will be -equal to the format passed to g_file_attribute_matcher_new(). -The output however, might not be identical, as the matcher may -decide to use a different order or omit needless parts. - - - a string describing the attributes the matcher matches - against or %NULL if @matcher was %NULL. - - - - - a #GFileAttributeMatcher. - - - - - - Unreferences @matcher. If the reference count falls below 1, -the @matcher is automatically freed. - - - - - - - a #GFileAttributeMatcher. - - - - - - - Used by g_file_set_attributes_from_info() when setting file attributes. - - Attribute value is unset (empty). - - - Attribute value is set. - - - Indicates an error in setting the value. - - - - The data types for file attributes. - - indicates an invalid or uninitalized type. - - - a null terminated UTF8 string. - - - a zero terminated string of non-zero bytes. - - - a boolean value. - - - an unsigned 4-byte/32-bit integer. - - - a signed 4-byte/32-bit integer. - - - an unsigned 8-byte/64-bit integer. - - - a signed 8-byte/64-bit integer. - - - a #GObject. - - - a %NULL terminated char **. Since 2.22 - - - - Flags used when copying or moving files. - - No flags set. - - - Overwrite any existing files - - - Make a backup of any existing files. - - - Don't follow symlinks. - - - Copy all file metadata instead of just default set used for copy (see #GFileInfo). - - - Don't use copy and delete fallback if native move not supported. - - - Leaves target file with default perms, instead of setting the source file perms. - - - - Flags used when an operation may create a file. - - No flags set. - - - Create a file that can only be - accessed by the current user. - - - Replace the destination - as if it didn't exist before. Don't try to keep any old - permissions, replace instead of following links. This - is generally useful if you're doing a "copy over" - rather than a "save new version of" replace operation. - You can think of it as "unlink destination" before - writing to it, although the implementation may not - be exactly like that. Since 2.20 - - - - #GFileDescriptorBased is implemented by streams (implementations of -#GInputStream or #GOutputStream) that are based on file descriptors. - -Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific -GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - Gets the underlying file descriptor. - - - The file descriptor - - - - - a #GFileDescriptorBased. - - - - - - Gets the underlying file descriptor. - - - The file descriptor - - - - - a #GFileDescriptorBased. - - - - - - - An interface for file descriptor based io objects. - - - The parent interface. - - - - - - - The file descriptor - - - - - a #GFileDescriptorBased. - - - - - - - - #GFileEnumerator allows you to operate on a set of #GFiles, -returning a #GFileInfo structure for each file enumerated (e.g. -g_file_enumerate_children() will return a #GFileEnumerator for each -of the children within a directory). - -To get the next file's information from a #GFileEnumerator, use -g_file_enumerator_next_file() or its asynchronous version, -g_file_enumerator_next_files_async(). Note that the asynchronous -version will return a list of #GFileInfos, whereas the -synchronous will only return the next file in the enumerator. - -The ordering of returned files is unspecified for non-Unix -platforms; for more information, see g_dir_read_name(). On Unix, -when operating on local files, returned files will be sorted by -inode number. Effectively you can assume that the ordering of -returned files will be stable between successive calls (and -applications) assuming the directory is unchanged. - -If your application needs a specific ordering, such as by name or -modification time, you will have to implement that in your -application code. - -To close a #GFileEnumerator, use g_file_enumerator_close(), or -its asynchronous version, g_file_enumerator_close_async(). Once -a #GFileEnumerator is closed, no further actions may be performed -on it, and it should be freed with g_object_unref(). - - - Asynchronously closes the file enumerator. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in -g_file_enumerator_close_finish(). - - - - - - - a #GFileEnumerator. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes closing a file enumerator, started from g_file_enumerator_close_async(). - -If the file enumerator was already closed when g_file_enumerator_close_async() -was called, then this function will report %G_IO_ERROR_CLOSED in @error, and -return %FALSE. If the file enumerator had pending operation when the close -operation was started, then this function will report %G_IO_ERROR_PENDING, and -return %FALSE. If @cancellable was not %NULL, then the operation may have been -cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be -returned. - - - %TRUE if the close operation has finished successfully. - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - Returns information for the next file in the enumerated object. -Will block until the information is available. The #GFileInfo -returned from this function will contain attributes that match the -attribute string that was passed when the #GFileEnumerator was created. - -See the documentation of #GFileEnumerator for information about the -order of returned files. - -On error, returns %NULL and sets @error to the error. If the -enumerator is at the end, %NULL will be returned and @error will -be unset. - - - A #GFileInfo or %NULL on error - or end of enumerator. Free the returned object with - g_object_unref() when no longer needed. - - - - - a #GFileEnumerator. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request information for a number of files from the enumerator asynchronously. -When all i/o for the operation is finished the @callback will be called with -the requested information. - -See the documentation of #GFileEnumerator for information about the -order of returned files. - -The callback can be called with less than @num_files files in case of error -or at the end of the enumerator. In case of a partial error the callback will -be called with any succeeding items and no error, and on the next request the -error will be reported. If a request is cancelled the callback will be called -with %G_IO_ERROR_CANCELLED. - -During an async request no other sync and async calls are allowed, and will -result in %G_IO_ERROR_PENDING errors. - -Any outstanding i/o request with higher priority (lower numerical value) will -be executed before an outstanding request with lower priority. Default -priority is %G_PRIORITY_DEFAULT. - - - - - - - a #GFileEnumerator. - - - - the number of file info objects to request - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - - - a #GList of #GFileInfos. You must free the list with - g_list_free() and unref the infos with g_object_unref() when you're - done with them. - - - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - Releases all resources used by this enumerator, making the -enumerator return %G_IO_ERROR_CLOSED on all calls. - -This will be automatically called when the last reference -is dropped, but you might want to call this function to make -sure resources are released as early as possible. - - - #TRUE on success or #FALSE on error. - - - - - a #GFileEnumerator. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously closes the file enumerator. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in -g_file_enumerator_close_finish(). - - - - - - - a #GFileEnumerator. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes closing a file enumerator, started from g_file_enumerator_close_async(). - -If the file enumerator was already closed when g_file_enumerator_close_async() -was called, then this function will report %G_IO_ERROR_CLOSED in @error, and -return %FALSE. If the file enumerator had pending operation when the close -operation was started, then this function will report %G_IO_ERROR_PENDING, and -return %FALSE. If @cancellable was not %NULL, then the operation may have been -cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be -returned. - - - %TRUE if the close operation has finished successfully. - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - Return a new #GFile which refers to the file named by @info in the source -directory of @enumerator. This function is primarily intended to be used -inside loops with g_file_enumerator_next_file(). - -This is a convenience method that's equivalent to: -|[<!-- language="C" --> - gchar *name = g_file_info_get_name (info); - GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), - name); -]| - - - a #GFile for the #GFileInfo passed it. - - - - - a #GFileEnumerator - - - - a #GFileInfo gotten from g_file_enumerator_next_file() - or the async equivalents. - - - - - - Get the #GFile container which is being enumerated. - - - the #GFile which is being enumerated. - - - - - a #GFileEnumerator - - - - - - Checks if the file enumerator has pending operations. - - - %TRUE if the @enumerator has pending operations. - - - - - a #GFileEnumerator. - - - - - - Checks if the file enumerator has been closed. - - - %TRUE if the @enumerator is closed. - - - - - a #GFileEnumerator. - - - - - - This is a version of g_file_enumerator_next_file() that's easier to -use correctly from C programs. With g_file_enumerator_next_file(), -the gboolean return value signifies "end of iteration or error", which -requires allocation of a temporary #GError. - -In contrast, with this function, a %FALSE return from -g_file_enumerator_iterate() *always* means -"error". End of iteration is signaled by @out_info or @out_child being %NULL. - -Another crucial difference is that the references for @out_info and -@out_child are owned by @direnum (they are cached as hidden -properties). You must not unref them in your own code. This makes -memory management significantly easier for C code in combination -with loops. - -Finally, this function optionally allows retrieving a #GFile as -well. - -You must specify at least one of @out_info or @out_child. - -The code pattern for correctly using g_file_enumerator_iterate() from C -is: - -|[ -direnum = g_file_enumerate_children (file, ...); -while (TRUE) - { - GFileInfo *info; - if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) - goto out; - if (!info) - break; - ... do stuff with "info"; do not unref it! ... - } - -out: - g_object_unref (direnum); // Note: frees the last @info -]| - - - - - - - an open #GFileEnumerator - - - - Output location for the next #GFileInfo, or %NULL - - - - Output location for the next #GFile, or %NULL - - - - a #GCancellable - - - - - - Returns information for the next file in the enumerated object. -Will block until the information is available. The #GFileInfo -returned from this function will contain attributes that match the -attribute string that was passed when the #GFileEnumerator was created. - -See the documentation of #GFileEnumerator for information about the -order of returned files. - -On error, returns %NULL and sets @error to the error. If the -enumerator is at the end, %NULL will be returned and @error will -be unset. - - - A #GFileInfo or %NULL on error - or end of enumerator. Free the returned object with - g_object_unref() when no longer needed. - - - - - a #GFileEnumerator. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request information for a number of files from the enumerator asynchronously. -When all i/o for the operation is finished the @callback will be called with -the requested information. - -See the documentation of #GFileEnumerator for information about the -order of returned files. - -The callback can be called with less than @num_files files in case of error -or at the end of the enumerator. In case of a partial error the callback will -be called with any succeeding items and no error, and on the next request the -error will be reported. If a request is cancelled the callback will be called -with %G_IO_ERROR_CANCELLED. - -During an async request no other sync and async calls are allowed, and will -result in %G_IO_ERROR_PENDING errors. - -Any outstanding i/o request with higher priority (lower numerical value) will -be executed before an outstanding request with lower priority. Default -priority is %G_PRIORITY_DEFAULT. - - - - - - - a #GFileEnumerator. - - - - the number of file info objects to request - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - - - a #GList of #GFileInfos. You must free the list with - g_list_free() and unref the infos with g_object_unref() when you're - done with them. - - - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - Sets the file enumerator as having pending operations. - - - - - - - a #GFileEnumerator. - - - - a boolean value. - - - - - - - - - - - - - - - - - - - - - - - - A #GFileInfo or %NULL on error - or end of enumerator. Free the returned object with - g_object_unref() when no longer needed. - - - - - a #GFileEnumerator. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFileEnumerator. - - - - the number of file info objects to request - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GList of #GFileInfos. You must free the list with - g_list_free() and unref the infos with g_object_unref() when you're - done with them. - - - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GFileEnumerator. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the close operation has finished successfully. - - - - - a #GFileEnumerator. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GFileIOStream provides io streams that both read and write to the same -file handle. - -GFileIOStream implements #GSeekable, which allows the io -stream to jump to arbitrary positions in the file and to truncate -the file, provided the filesystem of the file supports these -operations. - -To find the position of a file io stream, use -g_seekable_tell(). - -To find out if a file io stream supports seeking, use g_seekable_can_seek(). -To position a file io stream, use g_seekable_seek(). -To find out if a file io stream supports truncating, use -g_seekable_can_truncate(). To truncate a file io -stream, use g_seekable_truncate(). - -The default implementation of all the #GFileIOStream operations -and the implementation of #GSeekable just call into the same operations -on the output stream. - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the entity tag for the file when it has been written. -This must be called after the stream has been written -and closed, as the etag can change while writing. - - - the entity tag for the stream. - - - - - a #GFileIOStream. - - - - - - Queries a file io stream for the given @attributes. -This function blocks while querying the stream. For the asynchronous -version of this function, see g_file_io_stream_query_info_async(). -While the stream is blocked, the stream will set the pending flag -internally, and any other operations on the stream will fail with -%G_IO_ERROR_PENDING. - -Can fail if the stream was already closed (with @error being set to -%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being -set to %G_IO_ERROR_PENDING), or if querying info is not supported for -the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I -all cases of failure, %NULL will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will -be returned. - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously queries the @stream for a #GFileInfo. When completed, -@callback will be called with a #GAsyncResult which can be used to -finish the operation with g_file_io_stream_query_info_finish(). - -For the synchronous version of this function, see -g_file_io_stream_query_info(). - - - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finalizes the asynchronous query started -by g_file_io_stream_query_info_async(). - - - A #GFileInfo for the finished query. - - - - - a #GFileIOStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the entity tag for the file when it has been written. -This must be called after the stream has been written -and closed, as the etag can change while writing. - - - the entity tag for the stream. - - - - - a #GFileIOStream. - - - - - - Queries a file io stream for the given @attributes. -This function blocks while querying the stream. For the asynchronous -version of this function, see g_file_io_stream_query_info_async(). -While the stream is blocked, the stream will set the pending flag -internally, and any other operations on the stream will fail with -%G_IO_ERROR_PENDING. - -Can fail if the stream was already closed (with @error being set to -%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being -set to %G_IO_ERROR_PENDING), or if querying info is not supported for -the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I -all cases of failure, %NULL will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will -be returned. - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously queries the @stream for a #GFileInfo. When completed, -@callback will be called with a #GAsyncResult which can be used to -finish the operation with g_file_io_stream_query_info_finish(). - -For the synchronous version of this function, see -g_file_io_stream_query_info(). - - - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finalizes the asynchronous query started -by g_file_io_stream_query_info_async(). - - - A #GFileInfo for the finished query. - - - - - a #GFileIOStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - a #GFileIOStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - A #GFileInfo for the finished query. - - - - - a #GFileIOStream. - - - - a #GAsyncResult. - - - - - - - - - - the entity tag for the stream. - - - - - a #GFileIOStream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GFileIcon specifies an icon by pointing to an image file -to be used as icon. - - - - - Creates a new icon for a file. - - - a #GIcon for the given - @file, or %NULL on error. - - - - - a #GFile. - - - - - - Gets the #GFile associated with the given @icon. - - - a #GFile, or %NULL. - - - - - a #GIcon. - - - - - - The file containing the icon. - - - - - - - - An interface for writing VFS file handles. - - - The parent interface. - - - - - - - a new #GFile that is a duplicate - of the given #GFile. - - - - - input #GFile - - - - - - - - - - 0 if @file is not a valid #GFile, otherwise an - integer that can be used as hash value for the #GFile. - This function is intended for easily hashing a #GFile to - add to a #GHashTable or similar data structure. - - - - - #gconstpointer to a #GFile - - - - - - - - - - %TRUE if @file1 and @file2 are equal. - - - - - the first #GFile - - - - the second #GFile - - - - - - - - - - %TRUE if @file is native - - - - - input #GFile - - - - - - - - - - %TRUE if #GFile's backend supports the - given URI scheme, %FALSE if URI scheme is %NULL, - not supported, or #GFile is invalid. - - - - - input #GFile - - - - a string containing a URI scheme - - - - - - - - - - a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a string containing the #GFile's URI. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - - - - - a string containing the #GFile's parse name. - The returned string should be freed with g_free() - when no longer needed. - - - - - input #GFile - - - - - - - - - - a #GFile structure to the - parent of the given #GFile or %NULL if there is no parent. Free - the returned object with g_object_unref(). - - - - - input #GFile - - - - - - - - - - %TRUE if the @file's parent, grandparent, etc is @prefix, - %FALSE otherwise. - - - - - input #GFile - - - - input #GFile - - - - - - - - - - - - - - - - - - - - - - - - - - #GFile to the resolved path. - %NULL if @relative_path is %NULL or if @file is invalid. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a given relative path string - - - - - - - - - - a #GFile to the specified child, or - %NULL if the display name couldn't be converted. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - string to a possible child - - - - - - - - - - A #GFileEnumerator if successful, - %NULL on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileEnumerator or %NULL - if an error occurred. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileInfo for the given @file, or %NULL - on error. Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - an attribute query string - - - - a set of #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - - - - - #GFileInfo for given @file - or %NULL on error. Free the returned object with - g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileInfo or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an attribute query string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - an attribute query string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - #GFileInfo for given @file - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GMount where the @file is located - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - a #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - #GMount for given @file or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFile specifying what @file was renamed to, - or %NULL if there was an error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a string - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - a string - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileAttributeInfoList describing the settable attributes. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFileAttributeInfoList describing the writable namespaces. - When you are done with it, release it with - g_file_attribute_info_list_unref() - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the attribute was set, %FALSE otherwise. - - - - - input #GFile - - - - a string containing the attribute's name - - - - The type of the attribute - - - - a pointer to the value (or the pointer - itself if the type is a pointer type) - - - - a set of #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - %FALSE if there was any error, %TRUE otherwise. - - - - - input #GFile - - - - a #GFileInfo - - - - #GFileQueryInfoFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - a #GFileInfo - - - - a #GFileQueryInfoFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback - - - - a #gpointer - - - - - - - - - - %TRUE if the attributes were set correctly, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - a #GFileInfo - - - - - - - - - - #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to read - - - - a #GCancellable - - - - - - - - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileInputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a valid #GFileOutputStream - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - #GAsyncResult - - - - - - - - - - a #GFileOutputStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileOutputStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileOutputStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the file was deleted. %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE on successful trash, %FALSE otherwise. - - - - - #GFile to send to trash - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE on successful trash, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE on successful creation, %FALSE otherwise. - - - - - input #GFile - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE on successful directory creation, %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE on the creation of a new symlink, %FALSE otherwise. - - - - - a #GFile with the name of the symlink to create - - - - a string with the path for the target - of the new symlink - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE on success, %FALSE otherwise. - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with - progress information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - - - - - - - - - - - input #GFile - - - - destination #GFile - - - - set of #GFileCopyFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - function to callback with progress - information, or %NULL if progress information is not needed - - - - user data to pass to @progress_callback - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a %TRUE on success, %FALSE on error. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE on successful move, %FALSE otherwise. - - - - - #GFile pointing to the source location - - - - #GFile pointing to the destination location - - - - set of #GFileCopyFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - #GFileProgressCallback - function for updates - - - - gpointer to user data for - the callback function - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - a #GFile or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if successful. If an error has occurred, - this function will return %FALSE and set @error - appropriately if present. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a set of #GFileMonitorFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - #GFile to open - - - - a #GCancellable - - - - - - - - - - - - - - input #GFile - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileIOStream for the newly created - file, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - a #GFileIOStream or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GFile - - - - an optional [entity tag][gfile-etag] - for the current #GFile, or #NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - optional #GCancellable object, - %NULL to ignore - - - - - - - - - - - - - - input #GFile - - - - an [entity tag][gfile-etag] for the current #GFile, - or %NULL to ignore - - - - %TRUE if a backup should be created - - - - a set of #GFileCreateFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GFileIOStream, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction. - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the operation finished successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - flags affecting the operation - - - - a #GMountOperation, - or %NULL to avoid user interaction - - - - optional #GCancellable object, - %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the @file was ejected successfully. - %FALSE otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - - - - - input #GFile - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback to call - when the request is satisfied, or %NULL - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the operation finished successfully. %FALSE -otherwise. - - - - - input #GFile - - - - a #GAsyncResult - - - - - - - - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - #GFileMeasureFlags - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - - - - - - - - - a #GFile - - - - #GFileMeasureFlags - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable - - - - a #GFileMeasureProgressCallback - - - - user_data for @progress_callback - - - - a #GAsyncReadyCallback to call when complete - - - - the data to pass to callback function - - - - - - - - - - %TRUE if successful, with the out parameters set. - %FALSE otherwise, with @error set. - - - - - a #GFile - - - - the #GAsyncResult passed to your #GAsyncReadyCallback - - - - the number of bytes of disk space used - - - - the number of directories encountered - - - - the number of non-directories encountered - - - - - - - - Functionality for manipulating basic metadata for files. #GFileInfo -implements methods for getting information that all files should -contain, and allows for manipulation of extended attributes. - -See [GFileAttribute][gio-GFileAttribute] for more information on how -GIO handles file attributes. - -To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its -async variant). To obtain a #GFileInfo for a file input or output -stream, use g_file_input_stream_query_info() or -g_file_output_stream_query_info() (or their async variants). - -To change the actual attributes of a file, you should then set the -attribute in the #GFileInfo and call g_file_set_attributes_from_info() -or g_file_set_attributes_async() on a GFile. - -However, not all attributes can be changed in the file. For instance, -the actual size of a file cannot be changed via g_file_info_set_size(). -You may call g_file_query_settable_attributes() and -g_file_query_writable_namespaces() to discover the settable attributes -of a particular file at runtime. - -#GFileAttributeMatcher allows for searching through a #GFileInfo for -attributes. - - - Creates a new file info structure. - - - a #GFileInfo. - - - - - Clears the status information from @info. - - - - - - - a #GFileInfo. - - - - - - First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info, -and then copies all of the file attributes from @src_info to @dest_info. - - - - - - - source to copy attributes from. - - - - destination to copy attributes to. - - - - - - Duplicates a file info structure. - - - a duplicate #GFileInfo of @other. - - - - - a #GFileInfo. - - - - - - Gets the value of a attribute, formated as a string. -This escapes things as needed to make the string valid -UTF-8. - - - a UTF-8 string associated with the given @attribute, or - %NULL if the attribute wasn’t set. - When you're done with the string it must be freed with g_free(). - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the value of a boolean attribute. If the attribute does not -contain a boolean value, %FALSE will be returned. - - - the boolean value contained within the attribute. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the value of a byte string attribute. If the attribute does -not contain a byte string, %NULL will be returned. - - - the contents of the @attribute value as a byte string, or -%NULL otherwise. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the attribute type, value and status for an attribute key. - - - %TRUE if @info has an attribute named @attribute, - %FALSE otherwise. - - - - - a #GFileInfo - - - - a file attribute key - - - - return location for the attribute type, or %NULL - - - - return location for the - attribute value, or %NULL; the attribute value will not be %NULL - - - - return location for the attribute status, or %NULL - - - - - - Gets a signed 32-bit integer contained within the attribute. If the -attribute does not contain a signed 32-bit integer, or is invalid, -0 will be returned. - - - a signed 32-bit integer from the attribute. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets a signed 64-bit integer contained within the attribute. If the -attribute does not contain a signed 64-bit integer, or is invalid, -0 will be returned. - - - a signed 64-bit integer from the attribute. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the value of a #GObject attribute. If the attribute does -not contain a #GObject, %NULL will be returned. - - - a #GObject associated with the given @attribute, or -%NULL otherwise. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the attribute status for an attribute key. - - - a #GFileAttributeStatus for the given @attribute, or - %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. - - - - - a #GFileInfo - - - - a file attribute key - - - - - - Gets the value of a string attribute. If the attribute does -not contain a string, %NULL will be returned. - - - the contents of the @attribute value as a UTF-8 string, or -%NULL otherwise. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the value of a stringv attribute. If the attribute does -not contain a stringv, %NULL will be returned. - - - the contents of the @attribute value as a stringv, or -%NULL otherwise. Do not free. These returned strings are UTF-8. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the attribute type for an attribute key. - - - a #GFileAttributeType for the given @attribute, or -%G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets an unsigned 32-bit integer contained within the attribute. If the -attribute does not contain an unsigned 32-bit integer, or is invalid, -0 will be returned. - - - an unsigned 32-bit integer from the attribute. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets a unsigned 64-bit integer contained within the attribute. If the -attribute does not contain an unsigned 64-bit integer, or is invalid, -0 will be returned. - - - a unsigned 64-bit integer from the attribute. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Gets the file's content type. - - - a string containing the file's content type. - - - - - a #GFileInfo. - - - - - - Returns the #GDateTime representing the deletion date of the file, as -available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the -G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. - - - a #GDateTime, or %NULL. - - - - - a #GFileInfo. - - - - - - Gets a display name for a file. - - - a string containing the display name. - - - - - a #GFileInfo. - - - - - - Gets the edit name for a file. - - - a string containing the edit name. - - - - - a #GFileInfo. - - - - - - Gets the [entity tag][gfile-etag] for a given -#GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. - - - a string containing the value of the "etag:value" attribute. - - - - - a #GFileInfo. - - - - - - Gets a file's type (whether it is a regular file, symlink, etc). -This is different from the file's content type, see g_file_info_get_content_type(). - - - a #GFileType for the given file. - - - - - a #GFileInfo. - - - - - - Gets the icon for a file. - - - #GIcon for the given @info. - - - - - a #GFileInfo. - - - - - - Checks if a file is a backup file. - - - %TRUE if file is a backup file, %FALSE otherwise. - - - - - a #GFileInfo. - - - - - - Checks if a file is hidden. - - - %TRUE if the file is a hidden file, %FALSE otherwise. - - - - - a #GFileInfo. - - - - - - Checks if a file is a symlink. - - - %TRUE if the given @info is a symlink. - - - - - a #GFileInfo. - - - - - - Gets the modification time of the current @info and returns it as a -#GDateTime. - -This requires the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute. If -%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime -will have microsecond precision. - - - modification time, or %NULL if unknown - - - - - a #GFileInfo. - - - - - - Gets the modification time of the current @info and sets it -in @result. - Use g_file_info_get_modification_date_time() instead, as - #GTimeVal is deprecated due to the year 2038 problem. - - - - - - - a #GFileInfo. - - - - a #GTimeVal. - - - - - - Gets the name for a file. - - - a string containing the file name. - - - - - a #GFileInfo. - - - - - - Gets the file's size. - - - a #goffset containing the file's size. - - - - - a #GFileInfo. - - - - - - Gets the value of the sort_order attribute from the #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - - - a #gint32 containing the value of the "standard::sort_order" attribute. - - - - - a #GFileInfo. - - - - - - Gets the symbolic icon for a file. - - - #GIcon for the given @info. - - - - - a #GFileInfo. - - - - - - Gets the symlink target for a given #GFileInfo. - - - a string containing the symlink target. - - - - - a #GFileInfo. - - - - - - Checks if a file info structure has an attribute named @attribute. - - - %TRUE if @info has an attribute named @attribute, - %FALSE otherwise. - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Checks if a file info structure has an attribute in the -specified @name_space. - - - %TRUE if @info has an attribute in @name_space, - %FALSE otherwise. - - - - - a #GFileInfo. - - - - a file attribute namespace. - - - - - - Lists the file info structure's attributes. - - - a -null-terminated array of strings of all of the possible attribute -types for the given @name_space, or %NULL on error. - - - - - - - a #GFileInfo. - - - - a file attribute key's namespace, or %NULL to list - all attributes. - - - - - - Removes all cases of @attribute from @info if it exists. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - - - Sets the @attribute to contain the given value, if possible. To unset the -attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a #GFileAttributeType - - - - pointer to the value - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a boolean value. - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a byte string. - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a signed 32-bit integer - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - attribute name to set. - - - - int64 value to set attribute to. - - - - - - Sets @mask on @info to match specific attribute types. - - - - - - - a #GFileInfo. - - - - a #GFileAttributeMatcher. - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a #GObject. - - - - - - Sets the attribute status for an attribute key. This is only -needed by external code that implement g_file_set_attributes_from_info() -or similar functions. - -The attribute must exist in @info for this to work. Otherwise %FALSE -is returned and @info is unchanged. - - - %TRUE if the status was changed, %FALSE if the key was not set. - - - - - a #GFileInfo - - - - a file attribute key - - - - a #GFileAttributeStatus - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - a UTF-8 string. - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - -Sinze: 2.22 - - - - - - - a #GFileInfo. - - - - a file attribute key - - - - a %NULL - terminated array of UTF-8 strings. - - - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - an unsigned 32-bit integer. - - - - - - Sets the @attribute to contain the given @attr_value, -if possible. - - - - - - - a #GFileInfo. - - - - a file attribute key. - - - - an unsigned 64-bit integer. - - - - - - Sets the content type attribute for a given #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. - - - - - - - a #GFileInfo. - - - - a content type. See [GContentType][gio-GContentType] - - - - - - Sets the display name for the current #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. - - - - - - - a #GFileInfo. - - - - a string containing a display name. - - - - - - Sets the edit name for the current file. -See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. - - - - - - - a #GFileInfo. - - - - a string containing an edit name. - - - - - - Sets the file type in a #GFileInfo to @type. -See %G_FILE_ATTRIBUTE_STANDARD_TYPE. - - - - - - - a #GFileInfo. - - - - a #GFileType. - - - - - - Sets the icon for a given #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_ICON. - - - - - - - a #GFileInfo. - - - - a #GIcon. - - - - - - Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. -See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. - - - - - - - a #GFileInfo. - - - - a #gboolean. - - - - - - Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. -See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. - - - - - - - a #GFileInfo. - - - - a #gboolean. - - - - - - Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and -%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the -given date/time value. - - - - - - - a #GFileInfo. - - - - a #GDateTime. - - - - - - Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and -%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the -given time value. - Use g_file_info_set_modification_date_time() instead, as - #GTimeVal is deprecated due to the year 2038 problem. - - - - - - - a #GFileInfo. - - - - a #GTimeVal. - - - - - - Sets the name attribute for the current #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_NAME. - - - - - - - a #GFileInfo. - - - - a string containing a name. - - - - - - Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info -to the given size. - - - - - - - a #GFileInfo. - - - - a #goffset containing the file's size. - - - - - - Sets the sort order attribute in the file info structure. See -%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - - - - - - - a #GFileInfo. - - - - a sort order integer. - - - - - - Sets the symbolic icon for a given #GFileInfo. -See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. - - - - - - - a #GFileInfo. - - - - a #GIcon. - - - - - - Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info -to the given symlink target. - - - - - - - a #GFileInfo. - - - - a static string containing a path to a symlink target. - - - - - - Unsets a mask set by g_file_info_set_attribute_mask(), if one -is set. - - - - - - - #GFileInfo. - - - - - - - - - - GFileInputStream provides input streams that take their -content from a file. - -GFileInputStream implements #GSeekable, which allows the input -stream to jump to arbitrary positions in the file, provided the -filesystem of the file allows it. To find the position of a file -input stream, use g_seekable_tell(). To find out if a file input -stream supports seeking, use g_seekable_can_seek(). -To position a file input stream, use g_seekable_seek(). - - - - - - - - - - - - - - - Queries a file input stream the given @attributes. This function blocks -while querying the stream. For the asynchronous (non-blocking) version -of this function, see g_file_input_stream_query_info_async(). While the -stream is blocked, the stream will set the pending flag internally, and -any other operations on the stream will fail with %G_IO_ERROR_PENDING. - - - a #GFileInfo, or %NULL on error. - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Queries the stream information asynchronously. -When the operation is finished @callback will be called. -You can then call g_file_input_stream_query_info_finish() -to get the result of the operation. - -For the synchronous version of this function, -see g_file_input_stream_query_info(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set - - - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous info query operation. - - - #GFileInfo. - - - - - a #GFileInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Queries a file input stream the given @attributes. This function blocks -while querying the stream. For the asynchronous (non-blocking) version -of this function, see g_file_input_stream_query_info_async(). While the -stream is blocked, the stream will set the pending flag internally, and -any other operations on the stream will fail with %G_IO_ERROR_PENDING. - - - a #GFileInfo, or %NULL on error. - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Queries the stream information asynchronously. -When the operation is finished @callback will be called. -You can then call g_file_input_stream_query_info_finish() -to get the result of the operation. - -For the synchronous version of this function, -see g_file_input_stream_query_info(). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set - - - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous info query operation. - - - #GFileInfo. - - - - - a #GFileInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFileInfo, or %NULL on error. - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - a #GFileInputStream. - - - - a file attribute query string. - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - #GFileInfo. - - - - - a #GFileInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags that can be used with g_file_measure_disk_usage(). - - No flags set. - - - Report any error encountered - while traversing the directory tree. Normally errors are only - reported for the toplevel file. - - - Tally usage based on apparent file - sizes. Normally, the block-size is used, if available, as this is a - more accurate representation of disk space used. - Compare with `du --apparent-size`. - - - Do not cross mount point boundaries. - Compare with `du -x`. - - - - This callback type is used by g_file_measure_disk_usage() to make -periodic progress reports when measuring the amount of disk spaced -used by a directory. - -These calls are made on a best-effort basis and not all types of -#GFile will support them. At the minimum, however, one call will -always be made immediately. - -In the case that there is no support, @reporting will be set to -%FALSE (and the other values undefined) and no further calls will be -made. Otherwise, the @reporting will be %TRUE and the other values -all-zeros during the first (immediate) call. In this way, you can -know which type of progress UI to show without a delay. - -For g_file_measure_disk_usage() the callback is made directly. For -g_file_measure_disk_usage_async() the callback is made via the -default main context of the calling thread (ie: the same way that the -final async result would be reported). - -@current_size is in the same units as requested by the operation (see -%G_FILE_MEASURE_APPARENT_SIZE). - -The frequency of the updates is implementation defined, but is -ideally about once every 200ms. - -The last progress callback may or may not be equal to the final -result. Always check the async result to get the final value. - - - - - - - %TRUE if more reports will come - - - - the current cumulative size measurement - - - - the number of directories visited so far - - - - the number of non-directory files encountered - - - - the data passed to the original request for this callback - - - - - - Monitors a file or directory for changes. - -To obtain a #GFileMonitor for a file or directory, use -g_file_monitor(), g_file_monitor_file(), or -g_file_monitor_directory(). - -To get informed about changes to the file or directory you are -monitoring, connect to the #GFileMonitor::changed signal. The -signal will be emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that the monitor was created in -(though if the global default main context is blocked, this may -cause notifications to be blocked even if the thread-default -context is still running). - - - Cancels a file monitor. - - - always %TRUE - - - - - a #GFileMonitor. - - - - - - - - - - - - - - - - - - - - - - - - - - Cancels a file monitor. - - - always %TRUE - - - - - a #GFileMonitor. - - - - - - Emits the #GFileMonitor::changed signal if a change -has taken place. Should be called from file monitor -implementations only. - -Implementations are responsible to call this method from the -[thread-default main context][g-main-context-push-thread-default] of the -thread that the monitor was created in. - - - - - - - a #GFileMonitor. - - - - a #GFile. - - - - a #GFile. - - - - a set of #GFileMonitorEvent flags. - - - - - - Returns whether the monitor is canceled. - - - %TRUE if monitor is canceled. %FALSE otherwise. - - - - - a #GFileMonitor - - - - - - Sets the rate limit to which the @monitor will report -consecutive change events to the same file. - - - - - - - a #GFileMonitor. - - - - a non-negative integer with the limit in milliseconds - to poll for changes - - - - - - - - - - - - - - - - - - Emitted when @file has been changed. - -If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and -the information is available (and if supported by the backend), -@event_type may be %G_FILE_MONITOR_EVENT_RENAMED, -%G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT. - -In all cases @file will be a child of the monitored directory. For -renames, @file will be the old name and @other_file is the new -name. For "moved in" events, @file is the name of the file that -appeared and @other_file is the old name that it was moved from (in -another directory). For "moved out" events, @file is the name of -the file that used to be in this directory and @other_file is the -name of the file at its new location. - -It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as -equivalent to %G_FILE_MONITOR_EVENT_CREATED and -%G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to -%G_FILE_MONITOR_EVENT_DELETED, with extra information. -%G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create -pair. This is exactly how the events will be reported in the case -that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use. - -If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is -#G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the -old path, and @other_file will be set to a #GFile containing the new path. - -In all the other cases, @other_file will be set to #NULL. - - - - - - a #GFile. - - - - a #GFile or #NULL. - - - - a #GFileMonitorEvent. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - always %TRUE - - - - - a #GFileMonitor. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies what type of event a monitor event is. - - a file changed. - - - a hint that this was probably the last change in a set of changes. - - - a file was deleted. - - - a file was created. - - - a file attribute was changed. - - - the file location will soon be unmounted. - - - the file location was unmounted. - - - the file was moved -- only sent if the - (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set - - - the file was renamed within the - current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES - flag is set. Since: 2.46. - - - the file was moved into the - monitored directory from another location -- only sent if the - %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. - - - the file was moved out of the - monitored directory to another location -- only sent if the - %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46 - - - - Flags used to set what a #GFileMonitor will watch for. - - No flags set. - - - Watch for mount events. - - - Pair DELETED and CREATED events caused - by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED - event instead (NB: not supported on all backends; the default - behaviour -without specifying this flag- is to send single DELETED - and CREATED events). Deprecated since 2.46: use - %G_FILE_MONITOR_WATCH_MOVES instead. - - - Watch for changes to the file made - via another hard link. Since 2.36. - - - Watch for rename operations on a - monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED, - %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT - events to be emitted when possible. Since: 2.46. - - - - - - - GFileOutputStream provides output streams that write their -content to a file. - -GFileOutputStream implements #GSeekable, which allows the output -stream to jump to arbitrary positions in the file and to truncate -the file, provided the filesystem of the file supports these -operations. - -To find the position of a file output stream, use g_seekable_tell(). -To find out if a file output stream supports seeking, use -g_seekable_can_seek().To position a file output stream, use -g_seekable_seek(). To find out if a file output stream supports -truncating, use g_seekable_can_truncate(). To truncate a file output -stream, use g_seekable_truncate(). - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the entity tag for the file when it has been written. -This must be called after the stream has been written -and closed, as the etag can change while writing. - - - the entity tag for the stream. - - - - - a #GFileOutputStream. - - - - - - Queries a file output stream for the given @attributes. -This function blocks while querying the stream. For the asynchronous -version of this function, see g_file_output_stream_query_info_async(). -While the stream is blocked, the stream will set the pending flag -internally, and any other operations on the stream will fail with -%G_IO_ERROR_PENDING. - -Can fail if the stream was already closed (with @error being set to -%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being -set to %G_IO_ERROR_PENDING), or if querying info is not supported for -the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In -all cases of failure, %NULL will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will -be returned. - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously queries the @stream for a #GFileInfo. When completed, -@callback will be called with a #GAsyncResult which can be used to -finish the operation with g_file_output_stream_query_info_finish(). - -For the synchronous version of this function, see -g_file_output_stream_query_info(). - - - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finalizes the asynchronous query started -by g_file_output_stream_query_info_async(). - - - A #GFileInfo for the finished query. - - - - - a #GFileOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets the entity tag for the file when it has been written. -This must be called after the stream has been written -and closed, as the etag can change while writing. - - - the entity tag for the stream. - - - - - a #GFileOutputStream. - - - - - - Queries a file output stream for the given @attributes. -This function blocks while querying the stream. For the asynchronous -version of this function, see g_file_output_stream_query_info_async(). -While the stream is blocked, the stream will set the pending flag -internally, and any other operations on the stream will fail with -%G_IO_ERROR_PENDING. - -Can fail if the stream was already closed (with @error being set to -%G_IO_ERROR_CLOSED), the stream has pending operations (with @error being -set to %G_IO_ERROR_PENDING), or if querying info is not supported for -the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In -all cases of failure, %NULL will be returned. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will -be returned. - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously queries the @stream for a #GFileInfo. When completed, -@callback will be called with a #GAsyncResult which can be used to -finish the operation with g_file_output_stream_query_info_finish(). - -For the synchronous version of this function, see -g_file_output_stream_query_info(). - - - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finalizes the asynchronous query started -by g_file_output_stream_query_info_async(). - - - A #GFileInfo for the finished query. - - - - - a #GFileOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFileInfo for the @stream, or %NULL on error. - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - a #GFileOutputStream. - - - - a file attribute query string. - - - - the [I/O priority][gio-GIOScheduler] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - A #GFileInfo for the finished query. - - - - - a #GFileOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - the entity tag for the stream. - - - - - a #GFileOutputStream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - When doing file operations that may take a while, such as moving -a file or copying a file, a progress callback is used to pass how -far along that operation is to the application. - - - - - - - the current number of bytes in the operation. - - - - the total number of bytes in the operation. - - - - user data passed to the callback. - - - - - - Flags used when querying a #GFileInfo. - - No flags set. - - - Don't follow symlinks. - - - - When loading the partial contents of a file with g_file_load_partial_contents_async(), -it may become necessary to determine if any more data from the file should be loaded. -A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data -should be read, or %FALSE otherwise. - - - %TRUE if more data should be read back. %FALSE otherwise. - - - - - the data as currently read. - - - - the size of the data currently read. - - - - data passed to the callback. - - - - - - Indicates the file's on-disk type. - -On Windows systems a file will never have %G_FILE_TYPE_SYMBOLIC_LINK type; -use #GFileInfo and %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine -whether a file is a symlink or not. This is due to the fact that NTFS does -not have a single filesystem object type for symbolic links - it has -files that symlink to files, and directories that symlink to directories. -#GFileType enumeration cannot precisely represent this important distinction, -which is why all Windows symlinks will continue to be reported as -%G_FILE_TYPE_REGULAR or %G_FILE_TYPE_DIRECTORY. - - File's type is unknown. - - - File handle represents a regular file. - - - File handle represents a directory. - - - File handle represents a symbolic link - (Unix systems). - - - File is a "special" file, such as a socket, fifo, - block device, or character device. - - - File is a shortcut (Windows systems). - - - File is a mountable location. - - - - Completes partial file and directory names given a partial string by -looking in the file system for clues. Can return a list of possible -completion strings for widget implementations. - - - Creates a new filename completer. - - - a #GFilenameCompleter. - - - - - - - - - - - - - - - - Obtains a completion for @initial_text from @completer. - - - a completed string, or %NULL if no completion exists. - This string is not owned by GIO, so remember to g_free() it - when finished. - - - - - the filename completer. - - - - text to be completed. - - - - - - Gets an array of completion strings for a given initial text. - - - array of strings with possible completions for @initial_text. -This array must be freed by g_strfreev() when finished. - - - - - - - the filename completer. - - - - text to be completed. - - - - - - If @dirs_only is %TRUE, @completer will only -complete directory names, and not file names. - - - - - - - the filename completer. - - - - a #gboolean. - - - - - - Emitted when the file name completion information comes available. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Indicates a hint from the file system whether files should be -previewed in a file manager. Returned as the value of the key -#G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. - - Only preview files if user has explicitly requested it. - - - Preview files if user has requested preview of "local" files. - - - Never preview files. - - - - Base class for input stream implementations that perform some -kind of filtering operation on a base stream. Typical examples -of filtering operations are character set conversion, compression -and byte order flipping. - - - Gets the base stream for the filter stream. - - - a #GInputStream. - - - - - a #GFilterInputStream. - - - - - - Returns whether the base stream will be closed when @stream is -closed. - - - %TRUE if the base stream will be closed. - - - - - a #GFilterInputStream. - - - - - - Sets whether the base stream will be closed when @stream is closed. - - - - - - - a #GFilterInputStream. - - - - %TRUE to close the base stream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for output stream implementations that perform some -kind of filtering operation on a base stream. Typical examples -of filtering operations are character set conversion, compression -and byte order flipping. - - - Gets the base stream for the filter stream. - - - a #GOutputStream. - - - - - a #GFilterOutputStream. - - - - - - Returns whether the base stream will be closed when @stream is -closed. - - - %TRUE if the base stream will be closed. - - - - - a #GFilterOutputStream. - - - - - - Sets whether the base stream will be closed when @stream is closed. - - - - - - - a #GFilterOutputStream. - - - - %TRUE to close the base stream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Error codes returned by GIO functions. - -Note that this domain may be extended in future GLib releases. In -general, new error codes either only apply to new APIs, or else -replace %G_IO_ERROR_FAILED in cases that were not explicitly -distinguished before. You should therefore avoid writing code like -|[<!-- language="C" --> -if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED)) - { - // Assume that this is EPRINTERONFIRE - ... - } -]| -but should instead treat all unrecognized error codes the same as -#G_IO_ERROR_FAILED. - -See also #GPollableReturn for a cheaper way of returning -%G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError. - - Generic error condition for when an operation fails - and no more specific #GIOErrorEnum value is defined. - - - File not found. - - - File already exists. - - - File is a directory. - - - File is not a directory. - - - File is a directory that isn't empty. - - - File is not a regular file. - - - File is not a symbolic link. - - - File cannot be mounted. - - - Filename is too many characters. - - - Filename is invalid or contains invalid characters. - - - File contains too many symbolic links. - - - No space left on drive. - - - Invalid argument. - - - Permission denied. - - - Operation (or one of its parameters) not supported - - - File isn't mounted. - - - File is already mounted. - - - File was closed. - - - Operation was cancelled. See #GCancellable. - - - Operations are still pending. - - - File is read only. - - - Backup couldn't be created. - - - File's Entity Tag was incorrect. - - - Operation timed out. - - - Operation would be recursive. - - - File is busy. - - - Operation would block. - - - Host couldn't be found (remote operations). - - - Operation would merge files. - - - Operation failed and a helper program has - already interacted with the user. Do not display any error dialog. - - - The current process has too many files - open and can't open any more. Duplicate descriptors do count toward - this limit. Since 2.20 - - - The object has not been initialized. Since 2.22 - - - The requested address is already in use. Since 2.22 - - - Need more input to finish operation. Since 2.24 - - - The input data was invalid. Since 2.24 - - - A remote object generated an error that - doesn't correspond to a locally registered #GError error - domain. Use g_dbus_error_get_remote_error() to extract the D-Bus - error name and g_dbus_error_strip_remote_error() to fix up the - message so it matches what was received on the wire. Since 2.26. - - - Host unreachable. Since 2.26 - - - Network unreachable. Since 2.26 - - - Connection refused. Since 2.26 - - - Connection to proxy server failed. Since 2.26 - - - Proxy authentication failed. Since 2.26 - - - Proxy server needs authentication. Since 2.26 - - - Proxy connection is not allowed by ruleset. - Since 2.26 - - - Broken pipe. Since 2.36 - - - Connection closed by peer. Note that this - is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some - "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others - returned %G_IO_ERROR_FAILED. Now they should all return the same - value, which has this more logical name. Since 2.44. - - - Transport endpoint is not connected. Since 2.44 - - - Message too large. Since 2.48. - - - - #GIOExtension is an opaque data structure and can only be accessed -using the following functions. - - - Gets the name under which @extension was registered. - -Note that the same type may be registered as extension -for multiple extension points, under different names. - - - the name of @extension. - - - - - a #GIOExtension - - - - - - Gets the priority with which @extension was registered. - - - the priority of @extension - - - - - a #GIOExtension - - - - - - Gets the type associated with @extension. - - - the type of @extension - - - - - a #GIOExtension - - - - - - Gets a reference to the class for the type that is -associated with @extension. - - - the #GTypeClass for the type of @extension - - - - - a #GIOExtension - - - - - - - #GIOExtensionPoint is an opaque data structure and can only be accessed -using the following functions. - - - Finds a #GIOExtension for an extension point by name. - - - the #GIOExtension for @extension_point that has the - given name, or %NULL if there is no extension with that name - - - - - a #GIOExtensionPoint - - - - the name of the extension to get - - - - - - Gets a list of all extensions that implement this extension point. -The list is sorted by priority, beginning with the highest priority. - - - a #GList of - #GIOExtensions. The list is owned by GIO and should not be - modified. - - - - - - - a #GIOExtensionPoint - - - - - - Gets the required type for @extension_point. - - - the #GType that all implementations must have, - or #G_TYPE_INVALID if the extension point has no required type - - - - - a #GIOExtensionPoint - - - - - - Sets the required type for @extension_point to @type. -All implementations must henceforth have this type. - - - - - - - a #GIOExtensionPoint - - - - the #GType to require - - - - - - Registers @type as extension for the extension point with name -@extension_point_name. - -If @type has already been registered as an extension for this -extension point, the existing #GIOExtension object is returned. - - - a #GIOExtension object for #GType - - - - - the name of the extension point - - - - the #GType to register as extension - - - - the name for the extension - - - - the priority for the extension - - - - - - Looks up an existing extension point. - - - the #GIOExtensionPoint, or %NULL if there - is no registered extension point with the given name. - - - - - the name of the extension point - - - - - - Registers an extension point. - - - the new #GIOExtensionPoint. This object is - owned by GIO and should not be freed. - - - - - The name of the extension point - - - - - - - Provides an interface and default functions for loading and unloading -modules. This is used internally to make GIO extensible, but can also -be used by others to implement module loading. - - - - Creates a new GIOModule that will load the specific -shared library when in use. - - - a #GIOModule from given @filename, -or %NULL on error. - - - - - filename of the shared library module. - - - - - - Optional API for GIO modules to implement. - -Should return a list of all the extension points that may be -implemented in this module. - -This method will not be called in normal use, however it may be -called when probing existing modules and recording which extension -points that this model is used for. This means we won't have to -load and initialize this module unless its needed. - -If this function is not implemented by the module the module will -always be loaded, initialized and then unloaded on application -startup so that it can register its extension points during init. - -Note that a module need not actually implement all the extension -points that g_io_module_query() returns, since the exact list of -extension may depend on runtime issues. However all extension -points actually implemented must be returned by g_io_module_query() -(if defined). - -When installing a module that implements g_io_module_query() you must -run gio-querymodules in order to build the cache files required for -lazy loading. - -Since 2.56, this function should be named `g_io_<modulename>_query`, where -`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and -everything after the first dot removed, and with `-` replaced with `_` -throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. -Using the new symbol names avoids name clashes when building modules -statically. The old symbol names continue to be supported, but cannot be used -for static builds. - - - A %NULL-terminated array of strings, - listing the supported extension points of the module. The array - must be suitable for freeing with g_strfreev(). - - - - - - - Required API for GIO modules to implement. - -This function is run after the module has been loaded into GIO, -to initialize the module. Typically, this function will call -g_io_extension_point_implement(). - -Since 2.56, this function should be named `g_io_<modulename>_load`, where -`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and -everything after the first dot removed, and with `-` replaced with `_` -throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. -Using the new symbol names avoids name clashes when building modules -statically. The old symbol names continue to be supported, but cannot be used -for static builds. - - - - - - - a #GIOModule. - - - - - - Required API for GIO modules to implement. - -This function is run when the module is being unloaded from GIO, -to finalize the module. - -Since 2.56, this function should be named `g_io_<modulename>_unload`, where -`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and -everything after the first dot removed, and with `-` replaced with `_` -throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. -Using the new symbol names avoids name clashes when building modules -statically. The old symbol names continue to be supported, but cannot be used -for static builds. - - - - - - - a #GIOModule. - - - - - - - - - - Represents a scope for loading IO modules. A scope can be used for blocking -duplicate modules, or blocking a module you don't want to load. - -The scope can be used with g_io_modules_load_all_in_directory_with_scope() -or g_io_modules_scan_all_in_directory_with_scope(). - - - Block modules with the given @basename from being loaded when -this scope is used with g_io_modules_scan_all_in_directory_with_scope() -or g_io_modules_load_all_in_directory_with_scope(). - - - - - - - a module loading scope - - - - the basename to block - - - - - - Free a module scope. - - - - - - - a module loading scope - - - - - - Create a new scope for loading of IO modules. A scope can be used for -blocking duplicate modules, or blocking a module you don't want to load. - -Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules -which have the same base name as a module that has already been seen -in this scope. - - - the new module scope - - - - - flags for the new scope - - - - - - - Flags for use with g_io_module_scope_new(). - - No module scan flags - - - When using this scope to load or - scan modules, automatically block a modules which has the same base - basename as previously loaded module. - - - - Opaque class for defining and scheduling IO jobs. - - - Used from an I/O job to send a callback to be run in the thread -that the job was started from, waiting for the result (and thus -blocking the I/O job). - Use g_main_context_invoke(). - - - The return value of @func - - - - - a #GIOSchedulerJob - - - - a #GSourceFunc callback that will be called in the original thread - - - - data to pass to @func - - - - a #GDestroyNotify for @user_data, or %NULL - - - - - - Used from an I/O job to send a callback to be run asynchronously in -the thread that the job was started from. The callback will be run -when the main loop is available, but at that time the I/O job might -have finished. The return value from the callback is ignored. - -Note that if you are passing the @user_data from g_io_scheduler_push_job() -on to this function you have to ensure that it is not freed before -@func is called, either by passing %NULL as @notify to -g_io_scheduler_push_job() or by using refcounting for @user_data. - Use g_main_context_invoke(). - - - - - - - a #GIOSchedulerJob - - - - a #GSourceFunc callback that will be called in the original thread - - - - data to pass to @func - - - - a #GDestroyNotify for @user_data, or %NULL - - - - - - - I/O Job function. - -Long-running jobs should periodically check the @cancellable -to see if they have been cancelled. - - - %TRUE if this function should be called again to - complete the job, %FALSE if the job is complete (or cancelled) - - - - - a #GIOSchedulerJob. - - - - optional #GCancellable object, %NULL to ignore. - - - - the data to pass to callback function - - - - - - GIOStream represents an object that has both read and write streams. -Generally the two streams act as separate input and output streams, -but they share some common resources and state. For instance, for -seekable streams, both streams may use the same position. - -Examples of #GIOStream objects are #GSocketConnection, which represents -a two-way network connection; and #GFileIOStream, which represents a -file handle opened in read-write mode. - -To do the actual reading and writing you need to get the substreams -with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). - -The #GIOStream object owns the input and the output streams, not the other -way around, so keeping the substreams alive will not keep the #GIOStream -object alive. If the #GIOStream object is freed it will be closed, thus -closing the substreams, so even if the substreams stay alive they will -always return %G_IO_ERROR_CLOSED for all operations. - -To close a stream use g_io_stream_close() which will close the common -stream object and also the individual substreams. You can also close -the substreams themselves. In most cases this only marks the -substream as closed, so further I/O on it fails but common state in the -#GIOStream may still be open. However, some streams may support -"half-closed" states where one direction of the stream is actually shut down. - -Operations on #GIOStreams cannot be started while another operation on the -#GIOStream or its substreams is in progress. Specifically, an application can -read from the #GInputStream and write to the #GOutputStream simultaneously -(either in separate threads, or as asynchronous operations in the same -thread), but an application cannot start any #GIOStream operation while there -is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and -an application can’t start any #GInputStream or #GOutputStream operation -while there is a #GIOStream operation in progress. - -This is a product of individual stream operations being associated with a -given #GMainContext (the thread-default context at the time the operation was -started), rather than entire streams being associated with a single -#GMainContext. - -GIO may run operations on #GIOStreams from other (worker) threads, and this -may be exposed to application code in the behaviour of wrapper streams, such -as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs, -application code may only run operations on the base (wrapped) stream when -the wrapper stream is idle. Note that the semantics of such operations may -not be well-defined due to the state the wrapper stream leaves the base -stream in (though they are guaranteed not to crash). - - - Finishes an asynchronous io stream splice operation. - - - %TRUE on success, %FALSE otherwise. - - - - - a #GAsyncResult. - - - - - - Requests an asynchronous close of the stream, releasing resources -related to it. When the operation is finished @callback will be -called. You can then call g_io_stream_close_finish() to get -the result of the operation. - -For behaviour details see g_io_stream_close(). - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - - - - - - - a #GIOStream - - - - the io priority of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Closes a stream. - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GIOStream - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - - - - Gets the input stream for this object. This is used -for reading. - - - a #GInputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - Gets the output stream for this object. This is used for -writing. - - - a #GOutputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - Clears the pending flag on @stream. - - - - - - - a #GIOStream - - - - - - Closes the stream, releasing resources related to it. This will also -close the individual input and output streams, if they are not already -closed. - -Once the stream is closed, all other operations will return -%G_IO_ERROR_CLOSED. Closing a stream multiple times will not -return an error. - -Closing a stream will automatically flush any outstanding buffers -in the stream. - -Streams will be automatically closed when the last reference -is dropped, but you might want to call this function to make sure -resources are released as early as possible. - -Some streams might keep the backing store of the stream (e.g. a file -descriptor) open after the stream is closed. See the documentation for -the individual stream for details. - -On failure the first error that happened will be reported, but the -close operation will finish as much as possible. A stream that failed -to close will still return %G_IO_ERROR_CLOSED for all operations. -Still, it is important to check and report the error to the user, -otherwise there might be a loss of data as all data might not be written. - -If @cancellable is not NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. -Cancelling a close will still leave the stream closed, but some streams -can use a faster close that doesn't block to e.g. check errors. - -The default implementation of this method just calls close on the -individual input/output streams. - - - %TRUE on success, %FALSE on failure - - - - - a #GIOStream - - - - optional #GCancellable object, %NULL to ignore - - - - - - Requests an asynchronous close of the stream, releasing resources -related to it. When the operation is finished @callback will be -called. You can then call g_io_stream_close_finish() to get -the result of the operation. - -For behaviour details see g_io_stream_close(). - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - - - - - - - a #GIOStream - - - - the io priority of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Closes a stream. - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GIOStream - - - - a #GAsyncResult - - - - - - Gets the input stream for this object. This is used -for reading. - - - a #GInputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - Gets the output stream for this object. This is used for -writing. - - - a #GOutputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - Checks if a stream has pending actions. - - - %TRUE if @stream has pending actions. - - - - - a #GIOStream - - - - - - Checks if a stream is closed. - - - %TRUE if the stream is closed. - - - - - a #GIOStream - - - - - - Sets @stream to have actions pending. If the pending flag is -already set or @stream is closed, it will return %FALSE and set -@error. - - - %TRUE if pending was previously unset and is now set. - - - - - a #GIOStream - - - - - - Asyncronously splice the output stream of @stream1 to the input stream of -@stream2, and splice the output stream of @stream2 to the input stream of -@stream1. - -When the operation is finished @callback will be called. -You can then call g_io_stream_splice_finish() to get the -result of the operation. - - - - - - - a #GIOStream. - - - - a #GIOStream. - - - - a set of #GIOStreamSpliceFlags. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GInputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - - - - - a #GOutputStream, owned by the #GIOStream. -Do not free. - - - - - a #GIOStream - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GIOStream - - - - the io priority of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GIOStream - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GIOStreamSpliceFlags determine how streams should be spliced. - - Do not close either stream. - - - Close the first stream after - the splice. - - - Close the second stream after - the splice. - - - Wait for both splice operations to finish - before calling the callback. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GIcon is a very minimal interface for icons. It provides functions -for checking the equality of two icons, hashing of icons and -serializing an icon to and from strings. - -#GIcon does not provide the actual pixmap for the icon as this is out -of GIO's scope, however implementations of #GIcon may contain the name -of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). - -To obtain a hash of a #GIcon, see g_icon_hash(). - -To check if two #GIcons are equal, see g_icon_equal(). - -For serializing a #GIcon, use g_icon_serialize() and -g_icon_deserialize(). - -If you want to consume #GIcon (for example, in a toolkit) you must -be prepared to handle at least the three following cases: -#GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make -sense to have fast-paths for other cases (like handling #GdkPixbuf -directly, for example) but all compliant #GIcon implementations -outside of GIO must implement #GLoadableIcon. - -If your application or library provides one or more #GIcon -implementations you need to ensure that your new implementation also -implements #GLoadableIcon. Additionally, you must provide an -implementation of g_icon_serialize() that gives a result that is -understood by g_icon_deserialize(), yielding one of the built-in icon -types. - - - Deserializes a #GIcon previously serialized using g_icon_serialize(). - - - a #GIcon, or %NULL when deserialization fails. - - - - - a #GVariant created with g_icon_serialize() - - - - - - Gets a hash for an icon. - - - a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. - - - - - #gconstpointer to an icon object. - - - - - - Generate a #GIcon instance from @str. This function can fail if -@str is not valid - see g_icon_to_string() for discussion. - -If your application or library provides one or more #GIcon -implementations you need to ensure that each #GType is registered -with the type system prior to calling g_icon_new_for_string(). - - - An object implementing the #GIcon - interface or %NULL if @error is set. - - - - - A string obtained via g_icon_to_string(). - - - - - - Checks if two icons are equal. - - - %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. - - - - - pointer to the first #GIcon. - - - - pointer to the second #GIcon. - - - - - - Gets a hash for an icon. - - - a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. - - - - - #gconstpointer to an icon object. - - - - - - Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved -back by calling g_icon_deserialize() on the returned value. -As serialization will avoid using raw icon data when possible, it only -makes sense to transfer the #GVariant between processes on the same machine, -(as opposed to over the network), and within the same file system namespace. - - - a #GVariant, or %NULL when serialization fails. - - - - - a #GIcon - - - - - - Generates a textual representation of @icon that can be used for -serialization such as when passing @icon to a different process or -saving it to persistent storage. Use g_icon_new_for_string() to -get @icon back from the returned string. - -The encoding of the returned string is proprietary to #GIcon except -in the following two cases - -- If @icon is a #GFileIcon, the returned string is a native path - (such as `/path/to/my icon.png`) without escaping - if the #GFile for @icon is a native file. If the file is not - native, the returned string is the result of g_file_get_uri() - (such as `sftp://path/to/my%20icon.png`). - -- If @icon is a #GThemedIcon with exactly one name and no fallbacks, - the encoding is simply the name (such as `network-server`). - - - An allocated NUL-terminated UTF8 string or -%NULL if @icon can't be serialized. Use g_free() to free. - - - - - a #GIcon. - - - - - - - - - - - - - - Checks if two icons are equal. - - - %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. - - - - - pointer to the first #GIcon. - - - - pointer to the second #GIcon. - - - - - - Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved -back by calling g_icon_deserialize() on the returned value. -As serialization will avoid using raw icon data when possible, it only -makes sense to transfer the #GVariant between processes on the same machine, -(as opposed to over the network), and within the same file system namespace. - - - a #GVariant, or %NULL when serialization fails. - - - - - a #GIcon - - - - - - Generates a textual representation of @icon that can be used for -serialization such as when passing @icon to a different process or -saving it to persistent storage. Use g_icon_new_for_string() to -get @icon back from the returned string. - -The encoding of the returned string is proprietary to #GIcon except -in the following two cases - -- If @icon is a #GFileIcon, the returned string is a native path - (such as `/path/to/my icon.png`) without escaping - if the #GFile for @icon is a native file. If the file is not - native, the returned string is the result of g_file_get_uri() - (such as `sftp://path/to/my%20icon.png`). - -- If @icon is a #GThemedIcon with exactly one name and no fallbacks, - the encoding is simply the name (such as `network-server`). - - - An allocated NUL-terminated UTF8 string or -%NULL if @icon can't be serialized. Use g_free() to free. - - - - - a #GIcon. - - - - - - - GIconIface is used to implement GIcon types for various -different systems. See #GThemedIcon and #GLoadableIcon for -examples of how to implement this interface. - - - The parent interface. - - - - - - - a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. - - - - - #gconstpointer to an icon object. - - - - - - - - - - %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. - - - - - pointer to the first #GIcon. - - - - pointer to the second #GIcon. - - - - - - - - - - An allocated NUL-terminated UTF8 string or -%NULL if @icon can't be serialized. Use g_free() to free. - - - - - a #GIcon. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GVariant, or %NULL when serialization fails. - - - - - a #GIcon - - - - - - - - #GInetAddress represents an IPv4 or IPv6 internet address. Use -g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to -look up the #GInetAddress for a hostname. Use -g_resolver_lookup_by_address() or -g_resolver_lookup_by_address_async() to look up the hostname for a -#GInetAddress. - -To actually connect to a remote host, you will need a -#GInetSocketAddress (which includes a #GInetAddress as well as a -port number). - - - Creates a #GInetAddress for the "any" address (unassigned/"don't -care") for @family. - - - a new #GInetAddress corresponding to the "any" address -for @family. - Free the returned object with g_object_unref(). - - - - - the address family - - - - - - Creates a new #GInetAddress from the given @family and @bytes. -@bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for -%G_SOCKET_FAMILY_IPV6. - - - a new #GInetAddress corresponding to @family and @bytes. - Free the returned object with g_object_unref(). - - - - - raw address data - - - - - - the address family of @bytes - - - - - - Parses @string as an IP address and creates a new #GInetAddress. - - - a new #GInetAddress corresponding to @string, or %NULL if -@string could not be parsed. - Free the returned object with g_object_unref(). - - - - - a string representation of an IP address - - - - - - Creates a #GInetAddress for the loopback address for @family. - - - a new #GInetAddress corresponding to the loopback address -for @family. - Free the returned object with g_object_unref(). - - - - - the address family - - - - - - Gets the raw binary address data from @address. - - - a pointer to an internal array of the bytes in @address, -which should not be modified, stored, or freed. The size of this -array can be gotten with g_inet_address_get_native_size(). - - - - - a #GInetAddress - - - - - - Converts @address to string form. - - - a representation of @address as a string, which should be -freed after use. - - - - - a #GInetAddress - - - - - - Checks if two #GInetAddress instances are equal, e.g. the same address. - - - %TRUE if @address and @other_address are equal, %FALSE otherwise. - - - - - A #GInetAddress. - - - - Another #GInetAddress. - - - - - - Gets @address's family - - - @address's family - - - - - a #GInetAddress - - - - - - Tests whether @address is the "any" address for its family. - - - %TRUE if @address is the "any" address for its family. - - - - - a #GInetAddress - - - - - - Tests whether @address is a link-local address (that is, if it -identifies a host on a local network that is not connected to the -Internet). - - - %TRUE if @address is a link-local address. - - - - - a #GInetAddress - - - - - - Tests whether @address is the loopback address for its family. - - - %TRUE if @address is the loopback address for its family. - - - - - a #GInetAddress - - - - - - Tests whether @address is a global multicast address. - - - %TRUE if @address is a global multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is a link-local multicast address. - - - %TRUE if @address is a link-local multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is a node-local multicast address. - - - %TRUE if @address is a node-local multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is an organization-local multicast address. - - - %TRUE if @address is an organization-local multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is a site-local multicast address. - - - %TRUE if @address is a site-local multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is a multicast address. - - - %TRUE if @address is a multicast address. - - - - - a #GInetAddress - - - - - - Tests whether @address is a site-local address such as 10.0.0.1 -(that is, the address identifies a host on a local network that can -not be reached directly from the Internet, but which may have -outgoing Internet connectivity via a NAT or firewall). - - - %TRUE if @address is a site-local address. - - - - - a #GInetAddress - - - - - - Gets the size of the native raw binary address for @address. This -is the size of the data that you get from g_inet_address_to_bytes(). - - - the number of bytes used for the native version of @address. - - - - - a #GInetAddress - - - - - - Gets the raw binary address data from @address. - - - a pointer to an internal array of the bytes in @address, -which should not be modified, stored, or freed. The size of this -array can be gotten with g_inet_address_get_native_size(). - - - - - a #GInetAddress - - - - - - Converts @address to string form. - - - a representation of @address as a string, which should be -freed after use. - - - - - a #GInetAddress - - - - - - - - - - - - Whether this is the "any" address for its family. -See g_inet_address_get_is_any(). - - - - Whether this is a link-local address. -See g_inet_address_get_is_link_local(). - - - - Whether this is the loopback address for its family. -See g_inet_address_get_is_loopback(). - - - - Whether this is a global multicast address. -See g_inet_address_get_is_mc_global(). - - - - Whether this is a link-local multicast address. -See g_inet_address_get_is_mc_link_local(). - - - - Whether this is a node-local multicast address. -See g_inet_address_get_is_mc_node_local(). - - - - Whether this is an organization-local multicast address. -See g_inet_address_get_is_mc_org_local(). - - - - Whether this is a site-local multicast address. -See g_inet_address_get_is_mc_site_local(). - - - - Whether this is a multicast address. -See g_inet_address_get_is_multicast(). - - - - Whether this is a site-local address. -See g_inet_address_get_is_loopback(). - - - - - - - - - - - - - - - - - - - a representation of @address as a string, which should be -freed after use. - - - - - a #GInetAddress - - - - - - - - - - a pointer to an internal array of the bytes in @address, -which should not be modified, stored, or freed. The size of this -array can be gotten with g_inet_address_get_native_size(). - - - - - a #GInetAddress - - - - - - - - #GInetAddressMask represents a range of IPv4 or IPv6 addresses -described by a base address and a length indicating how many bits -of the base address are relevant for matching purposes. These are -often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". - - - - Creates a new #GInetAddressMask representing all addresses whose -first @length bits match @addr. - - - a new #GInetAddressMask, or %NULL on error - - - - - a #GInetAddress - - - - number of bits of @addr to use - - - - - - Parses @mask_string as an IP address and (optional) length, and -creates a new #GInetAddressMask. The length, if present, is -delimited by a "/". If it is not present, then the length is -assumed to be the full length of the address. - - - a new #GInetAddressMask corresponding to @string, or %NULL -on error. - - - - - an IP address or address/length string - - - - - - Tests if @mask and @mask2 are the same mask. - - - whether @mask and @mask2 are the same mask - - - - - a #GInetAddressMask - - - - another #GInetAddressMask - - - - - - Gets @mask's base address - - - @mask's base address - - - - - a #GInetAddressMask - - - - - - Gets the #GSocketFamily of @mask's address - - - the #GSocketFamily of @mask's address - - - - - a #GInetAddressMask - - - - - - Gets @mask's length - - - @mask's length - - - - - a #GInetAddressMask - - - - - - Tests if @address falls within the range described by @mask. - - - whether @address falls within the range described by -@mask. - - - - - a #GInetAddressMask - - - - a #GInetAddress - - - - - - Converts @mask back to its corresponding string form. - - - a string corresponding to @mask. - - - - - a #GInetAddressMask - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An IPv4 or IPv6 socket address; that is, the combination of a -#GInetAddress and a port number. - - - - Creates a new #GInetSocketAddress for @address and @port. - - - a new #GInetSocketAddress - - - - - a #GInetAddress - - - - a port number - - - - - - Creates a new #GInetSocketAddress for @address and @port. - -If @address is an IPv6 address, it can also contain a scope ID -(separated from the address by a `%`). - - - a new #GInetSocketAddress, or %NULL if @address cannot be -parsed. - - - - - the string form of an IP address - - - - a port number - - - - - - Gets @address's #GInetAddress. - - - the #GInetAddress for @address, which must be -g_object_ref()'d if it will be stored - - - - - a #GInetSocketAddress - - - - - - Gets the `sin6_flowinfo` field from @address, -which must be an IPv6 address. - - - the flowinfo field - - - - - a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress - - - - - - Gets @address's port. - - - the port for @address - - - - - a #GInetSocketAddress - - - - - - Gets the `sin6_scope_id` field from @address, -which must be an IPv6 address. - - - the scope id field - - - - - a %G_SOCKET_FAMILY_IPV6 #GInetAddress - - - - - - - - - The `sin6_flowinfo` field, for IPv6 addresses. - - - - - - - - - - - - - - - - - - - - - - - - - - #GInitable is implemented by objects that can fail during -initialization. If an object implements this interface then -it must be initialized as the first thing after construction, -either via g_initable_init() or g_async_initable_init_async() -(the latter is only available if it also implements #GAsyncInitable). - -If the object is not initialized, or initialization returns with an -error, then all operations on the object except g_object_ref() and -g_object_unref() are considered to be invalid, and have undefined -behaviour. They will often fail with g_critical() or g_warning(), but -this must not be relied on. - -Users of objects implementing this are not intended to use -the interface method directly, instead it will be used automatically -in various ways. For C applications you generally just call -g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. -This will call g_initable_init() under the cover, returning %NULL and -setting a #GError on failure (at which point the instance is -unreferenced). - -For bindings in languages where the native constructor supports -exceptions the binding could check for objects implemention %GInitable -during normal construction and automatically initialize them, throwing -an exception on failure. - - - Helper function for constructing #GInitable object. This is -similar to g_object_new() but also initializes the object -and returns %NULL, setting an error on failure. - - - a newly allocated - #GObject, or %NULL on error - - - - - a #GType supporting #GInitable. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GError location to store the error occurring, or %NULL to - ignore. - - - - the name of the first property, or %NULL if no - properties - - - - the value if the first property, followed by and other property - value pairs, and ended by %NULL. - - - - - - Helper function for constructing #GInitable object. This is -similar to g_object_new_valist() but also initializes the object -and returns %NULL, setting an error on failure. - - - a newly allocated - #GObject, or %NULL on error - - - - - a #GType supporting #GInitable. - - - - the name of the first property, followed by -the value, and other property value pairs, and ended by %NULL. - - - - The var args list generated from @first_property_name. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Helper function for constructing #GInitable object. This is -similar to g_object_newv() but also initializes the object -and returns %NULL, setting an error on failure. - Use g_object_new_with_properties() and -g_initable_init() instead. See #GParameter for more information. - - - a newly allocated - #GObject, or %NULL on error - - - - - a #GType supporting #GInitable. - - - - the number of parameters in @parameters - - - - the parameters to use to construct the object - - - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Initializes the object implementing the interface. - -This method is intended for language bindings. If writing in C, -g_initable_new() should typically be used instead. - -The object must be initialized before any real use after initial -construction, either with this function or g_async_initable_init_async(). - -Implementations may also support cancellation. If @cancellable is not %NULL, -then initialization can be cancelled by triggering the cancellable object -from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and -the object doesn't support cancellable initialization the error -%G_IO_ERROR_NOT_SUPPORTED will be returned. - -If the object is not initialized, or initialization returns with an -error, then all operations on the object except g_object_ref() and -g_object_unref() are considered to be invalid, and have undefined -behaviour. See the [introduction][ginitable] for more details. - -Callers should not assume that a class which implements #GInitable can be -initialized multiple times, unless the class explicitly documents itself as -supporting this. Generally, a class’ implementation of init() can assume -(and assert) that it will only be called once. Previously, this documentation -recommended all #GInitable implementations should be idempotent; that -recommendation was relaxed in GLib 2.54. - -If a class explicitly supports being initialized multiple times, it is -recommended that the method is idempotent: multiple calls with the same -arguments should return the same results. Only the first call initializes -the object; further calls return the result of the first call. - -One reason why a class might need to support idempotent initialization is if -it is designed to be used via the singleton pattern, with a -#GObjectClass.constructor that sometimes returns an existing instance. -In this pattern, a caller would expect to be able to call g_initable_init() -on the result of g_object_new(), regardless of whether it is in fact a new -instance. - - - %TRUE if successful. If an error has occurred, this function will - return %FALSE and set @error appropriately if present. - - - - - a #GInitable. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Initializes the object implementing the interface. - -This method is intended for language bindings. If writing in C, -g_initable_new() should typically be used instead. - -The object must be initialized before any real use after initial -construction, either with this function or g_async_initable_init_async(). - -Implementations may also support cancellation. If @cancellable is not %NULL, -then initialization can be cancelled by triggering the cancellable object -from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and -the object doesn't support cancellable initialization the error -%G_IO_ERROR_NOT_SUPPORTED will be returned. - -If the object is not initialized, or initialization returns with an -error, then all operations on the object except g_object_ref() and -g_object_unref() are considered to be invalid, and have undefined -behaviour. See the [introduction][ginitable] for more details. - -Callers should not assume that a class which implements #GInitable can be -initialized multiple times, unless the class explicitly documents itself as -supporting this. Generally, a class’ implementation of init() can assume -(and assert) that it will only be called once. Previously, this documentation -recommended all #GInitable implementations should be idempotent; that -recommendation was relaxed in GLib 2.54. - -If a class explicitly supports being initialized multiple times, it is -recommended that the method is idempotent: multiple calls with the same -arguments should return the same results. Only the first call initializes -the object; further calls return the result of the first call. - -One reason why a class might need to support idempotent initialization is if -it is designed to be used via the singleton pattern, with a -#GObjectClass.constructor that sometimes returns an existing instance. -In this pattern, a caller would expect to be able to call g_initable_init() -on the result of g_object_new(), regardless of whether it is in fact a new -instance. - - - %TRUE if successful. If an error has occurred, this function will - return %FALSE and set @error appropriately if present. - - - - - a #GInitable. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - Provides an interface for initializing object such that initialization -may fail. - - - The parent interface. - - - - - - - %TRUE if successful. If an error has occurred, this function will - return %FALSE and set @error appropriately if present. - - - - - a #GInitable. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - Structure used for scatter/gather data input when receiving multiple -messages or packets in one go. You generally pass in an array of empty -#GInputVectors and the operation will use all the buffers as if they -were one buffer, and will set @bytes_received to the total number of bytes -received across all #GInputVectors. - -This structure closely mirrors `struct mmsghdr` and `struct msghdr` from -the POSIX sockets API (see `man 2 recvmmsg`). - -If @address is non-%NULL then it is set to the source address the message -was received from, and the caller must free it afterwards. - -If @control_messages is non-%NULL then it is set to an array of control -messages received with the message (if any), and the caller must free it -afterwards. @num_control_messages is set to the number of elements in -this array, which may be zero. - -Flags relevant to this message will be returned in @flags. For example, -`MSG_EOR` or `MSG_TRUNC`. - - - return location - for a #GSocketAddress, or %NULL - - - - pointer to an - array of input vectors - - - - - - the number of input vectors pointed to by @vectors - - - - will be set to the number of bytes that have been - received - - - - collection of #GSocketMsgFlags for the received message, - outputted by the call - - - - return location for a - caller-allocated array of #GSocketControlMessages, or %NULL - - - - - - return location for the number of - elements in @control_messages - - - - - #GInputStream has functions to read from a stream (g_input_stream_read()), -to close a stream (g_input_stream_close()) and to skip some content -(g_input_stream_skip()). - -To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). - -See the documentation for #GIOStream for details of thread safety of -streaming APIs. - -All of these functions have async variants too. - - - Requests an asynchronous closes of the stream, releasing resources related to it. -When the operation is finished @callback will be called. -You can then call g_input_stream_close_finish() to get the result of the -operation. - -For behaviour details see g_input_stream_close(). - -The asynchronous methods have a default fallback that uses threads to implement -asynchronicity, so they are optional for inheriting classes. However, if you -override one you must override all. - - - - - - - A #GInputStream. - - - - the [I/O priority][io-priority] of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes closing a stream asynchronously, started from g_input_stream_close_async(). - - - %TRUE if the stream was closed successfully. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - Request an asynchronous read of @count bytes from the stream into the buffer -starting at @buffer. When the operation is finished @callback will be called. -You can then call g_input_stream_read_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed on @stream, and will -result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes read into the buffer will be passed to the -callback. It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file, but generally we try to read -as many bytes as requested. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -Any outstanding i/o request with higher priority (lower numerical value) will -be executed before an outstanding request with lower priority. Default -priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads to implement -asynchronicity, so they are optional for inheriting classes. However, if you -override one you must override all. - - - - - - - A #GInputStream. - - - - - a buffer to read data into (which should be at least count bytes long). - - - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] -of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous stream read operation. - - - number of bytes read in, or -1 on error, or 0 on end of file. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - Tries to skip @count bytes from the stream. Will block during the operation. - -This is identical to g_input_stream_read(), from a behaviour standpoint, -but the bytes that are skipped are not returned to the user. Some -streams have an implementation that is more efficient than reading the data. - -This function is optional for inherited classes, as the default implementation -emulates it using read. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - - - Number of bytes skipped, or -1 on error - - - - - a #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous skip of @count bytes from the stream. -When the operation is finished @callback will be called. -You can then call g_input_stream_skip_finish() to get the result -of the operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes skipped will be passed to the callback. -It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file, but generally we try to skip -as many bytes as requested. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -Any outstanding i/o request with higher priority (lower numerical value) -will be executed before an outstanding request with lower priority. -Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads to -implement asynchronicity, so they are optional for inheriting classes. -However, if you override one, you must override all. - - - - - - - A #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream skip operation. - - - the size of the bytes skipped, or `-1` on error. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - Clears the pending flag on @stream. - - - - - - - input stream - - - - - - Closes the stream, releasing resources related to it. - -Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. -Closing a stream multiple times will not return an error. - -Streams will be automatically closed when the last reference -is dropped, but you might want to call this function to make sure -resources are released as early as possible. - -Some streams might keep the backing store of the stream (e.g. a file descriptor) -open after the stream is closed. See the documentation for the individual -stream for details. - -On failure the first error that happened will be reported, but the close -operation will finish as much as possible. A stream that failed to -close will still return %G_IO_ERROR_CLOSED for all operations. Still, it -is important to check and report the error to the user. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. -Cancelling a close will still leave the stream closed, but some streams -can use a faster close that doesn't block to e.g. check errors. - - - %TRUE on success, %FALSE on failure - - - - - A #GInputStream. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Requests an asynchronous closes of the stream, releasing resources related to it. -When the operation is finished @callback will be called. -You can then call g_input_stream_close_finish() to get the result of the -operation. - -For behaviour details see g_input_stream_close(). - -The asynchronous methods have a default fallback that uses threads to implement -asynchronicity, so they are optional for inheriting classes. However, if you -override one you must override all. - - - - - - - A #GInputStream. - - - - the [I/O priority][io-priority] of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes closing a stream asynchronously, started from g_input_stream_close_async(). - - - %TRUE if the stream was closed successfully. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - Checks if an input stream has pending actions. - - - %TRUE if @stream has pending actions. - - - - - input stream. - - - - - - Checks if an input stream is closed. - - - %TRUE if the stream is closed. - - - - - input stream. - - - - - - Tries to read @count bytes from the stream into the buffer starting at -@buffer. Will block during this read. - -If count is zero returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes read into the buffer is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -The returned @buffer is not a nul-terminated string, it can contain nul bytes -at any position, and this function doesn't nul-terminate the @buffer. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - - - Number of bytes read, or -1 on error, or 0 on end of file. - - - - - a #GInputStream. - - - - - a buffer to read data into (which should be at least count bytes long). - - - - - - the number of bytes that will be read from the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tries to read @count bytes from the stream into the buffer starting at -@buffer. Will block during this read. - -This function is similar to g_input_stream_read(), except it tries to -read as many bytes as requested, only stopping on an error or end of stream. - -On a successful read of @count bytes, or if we reached the end of the -stream, %TRUE is returned, and @bytes_read is set to the number of bytes -read into @buffer. - -If there is an error during the operation %FALSE is returned and @error -is set to indicate the error status. - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_read will be set to the number of bytes that were successfully -read before the error was encountered. This functionality is only -available from C. If you need it from another language then you must -write your own loop around g_input_stream_read(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GInputStream. - - - - - a buffer to read data into (which should be at least count bytes long). - - - - - - the number of bytes that will be read from the stream - - - - location to store the number of bytes that was read from the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous read of @count bytes from the stream into the -buffer starting at @buffer. - -This is the asynchronous equivalent of g_input_stream_read_all(). - -Call g_input_stream_read_all_finish() to collect the result. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - - - - - - - A #GInputStream - - - - - a buffer to read data into (which should be at least count bytes long) - - - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous stream read operation started with -g_input_stream_read_all_async(). - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_read will be set to the number of bytes that were successfully -read before the error was encountered. This functionality is only -available from C. If you need it from another language then you must -write your own loop around g_input_stream_read_async(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GInputStream - - - - a #GAsyncResult - - - - location to store the number of bytes that was read from the stream - - - - - - Request an asynchronous read of @count bytes from the stream into the buffer -starting at @buffer. When the operation is finished @callback will be called. -You can then call g_input_stream_read_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed on @stream, and will -result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes read into the buffer will be passed to the -callback. It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file, but generally we try to read -as many bytes as requested. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -Any outstanding i/o request with higher priority (lower numerical value) will -be executed before an outstanding request with lower priority. Default -priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads to implement -asynchronicity, so they are optional for inheriting classes. However, if you -override one you must override all. - - - - - - - A #GInputStream. - - - - - a buffer to read data into (which should be at least count bytes long). - - - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] -of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Like g_input_stream_read(), this tries to read @count bytes from -the stream in a blocking fashion. However, rather than reading into -a user-supplied buffer, this will create a new #GBytes containing -the data that was read. This may be easier to use from language -bindings. - -If count is zero, returns a zero-length #GBytes and does nothing. A -value of @count larger than %G_MAXSSIZE will cause a -%G_IO_ERROR_INVALID_ARGUMENT error. - -On success, a new #GBytes is returned. It is not an error if the -size of this object is not the same as the requested size, as it -can happen e.g. near the end of a file. A zero-length #GBytes is -returned on end of file (or if @count is zero), but never -otherwise. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error %NULL is returned and @error is set accordingly. - - - a new #GBytes, or %NULL on error - - - - - a #GInputStream. - - - - maximum number of bytes that will be read from the stream. Common -values include 4096 and 8192. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous read of @count bytes from the stream into a -new #GBytes. When the operation is finished @callback will be -called. You can then call g_input_stream_read_bytes_finish() to get the -result of the operation. - -During an async request no other sync and async calls are allowed -on @stream, and will result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a -%G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the new #GBytes will be passed to the callback. It is -not an error if this is smaller than the requested size, as it can -happen e.g. near the end of a file, but generally we try to read as -many bytes as requested. Zero is returned on end of file (or if -@count is zero), but never otherwise. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - - - - - - - A #GInputStream. - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous stream read-into-#GBytes operation. - - - the newly-allocated #GBytes, or %NULL on error - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - Finishes an asynchronous stream read operation. - - - number of bytes read in, or -1 on error, or 0 on end of file. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - Sets @stream to have actions pending. If the pending flag is -already set or @stream is closed, it will return %FALSE and set -@error. - - - %TRUE if pending was previously unset and is now set. - - - - - input stream - - - - - - Tries to skip @count bytes from the stream. Will block during the operation. - -This is identical to g_input_stream_read(), from a behaviour standpoint, -but the bytes that are skipped are not returned to the user. Some -streams have an implementation that is more efficient than reading the data. - -This function is optional for inherited classes, as the default implementation -emulates it using read. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - - - Number of bytes skipped, or -1 on error - - - - - a #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous skip of @count bytes from the stream. -When the operation is finished @callback will be called. -You can then call g_input_stream_skip_finish() to get the result -of the operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes skipped will be passed to the callback. -It is not an error if this is not the same as the requested size, as it -can happen e.g. near the end of a file, but generally we try to skip -as many bytes as requested. Zero is returned on end of file -(or if @count is zero), but never otherwise. - -Any outstanding i/o request with higher priority (lower numerical value) -will be executed before an outstanding request with lower priority. -Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads to -implement asynchronicity, so they are optional for inheriting classes. -However, if you override one, you must override all. - - - - - - - A #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream skip operation. - - - the size of the bytes skipped, or `-1` on error. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Number of bytes skipped, or -1 on error - - - - - a #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GInputStream. - - - - - a buffer to read data into (which should be at least count bytes long). - - - - - - the number of bytes that will be read from the stream - - - - the [I/O priority][io-priority] -of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - number of bytes read in, or -1 on error, or 0 on end of file. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - A #GInputStream. - - - - the number of bytes that will be skipped from the stream - - - - the [I/O priority][io-priority] of the request - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - the size of the bytes skipped, or `-1` on error. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - A #GInputStream. - - - - the [I/O priority][io-priority] of the request - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if the stream was closed successfully. - - - - - a #GInputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Structure used for scatter/gather data input. -You generally pass in an array of #GInputVectors -and the operation will store the read data starting in the -first buffer, switching to the next as needed. - - - Pointer to a buffer where data will be written. - - - - the available size in @buffer. - - - - - - - - - - - - - - - - - - - #GListModel is an interface that represents a mutable list of -#GObjects. Its main intention is as a model for various widgets in -user interfaces, such as list views, but it can also be used as a -convenient method of returning lists of data, with support for -updates. - -Each object in the list may also report changes in itself via some -mechanism (normally the #GObject::notify signal). Taken together -with the #GListModel::items-changed signal, this provides for a list -that can change its membership, and in which the members can change -their individual properties. - -A good example would be the list of visible wireless network access -points, where each access point can report dynamic properties such as -signal strength. - -It is important to note that the #GListModel itself does not report -changes to the individual items. It only reports changes to the list -membership. If you want to observe changes to the objects themselves -then you need to connect signals to the objects that you are -interested in. - -All items in a #GListModel are of (or derived from) the same type. -g_list_model_get_item_type() returns that type. The type may be an -interface, in which case all objects in the list must implement it. - -The semantics are close to that of an array: -g_list_model_get_n_items() returns the number of items in the list and -g_list_model_get_item() returns an item at a (0-based) position. In -order to allow implementations to calculate the list length lazily, -you can also iterate over items: starting from 0, repeatedly call -g_list_model_get_item() until it returns %NULL. - -An implementation may create objects lazily, but must take care to -return the same object for a given position until all references to -it are gone. - -On the other side, a consumer is expected only to hold references on -objects that are currently "user visible", in order to faciliate the -maximum level of laziness in the implementation of the list and to -reduce the required number of signal connections at a given time. - -This interface is intended only to be used from a single thread. The -thread in which it is appropriate to use it depends on the particular -implementation, but typically it will be from the thread that owns -the [thread-default main context][g-main-context-push-thread-default] -in effect at the time that the model was created. - - - Get the item at @position. If @position is greater than the number of -items in @list, %NULL is returned. - -%NULL is never returned for an index that is smaller than the length -of the list. See g_list_model_get_n_items(). - - - the object at @position. - - - - - a #GListModel - - - - the position of the item to fetch - - - - - - Gets the type of the items in @list. All items returned from -g_list_model_get_type() are of that type or a subtype, or are an -implementation of that interface. - -The item type of a #GListModel can not change during the life of the -model. - - - the #GType of the items contained in @list. - - - - - a #GListModel - - - - - - Gets the number of items in @list. - -Depending on the model implementation, calling this function may be -less efficient than iterating the list with increasing values for -@position until g_list_model_get_item() returns %NULL. - - - the number of items in @list. - - - - - a #GListModel - - - - - - Get the item at @position. If @position is greater than the number of -items in @list, %NULL is returned. - -%NULL is never returned for an index that is smaller than the length -of the list. See g_list_model_get_n_items(). - - - the item at @position. - - - - - a #GListModel - - - - the position of the item to fetch - - - - - - Gets the type of the items in @list. All items returned from -g_list_model_get_type() are of that type or a subtype, or are an -implementation of that interface. - -The item type of a #GListModel can not change during the life of the -model. - - - the #GType of the items contained in @list. - - - - - a #GListModel - - - - - - Gets the number of items in @list. - -Depending on the model implementation, calling this function may be -less efficient than iterating the list with increasing values for -@position until g_list_model_get_item() returns %NULL. - - - the number of items in @list. - - - - - a #GListModel - - - - - - Get the item at @position. If @position is greater than the number of -items in @list, %NULL is returned. - -%NULL is never returned for an index that is smaller than the length -of the list. See g_list_model_get_n_items(). - - - the object at @position. - - - - - a #GListModel - - - - the position of the item to fetch - - - - - - Emits the #GListModel::items-changed signal on @list. - -This function should only be called by classes implementing -#GListModel. It has to be called after the internal representation -of @list has been updated, because handlers connected to this signal -might query the new state of the list. - -Implementations must only make changes to the model (as visible to -its consumer) in places that will not cause problems for that -consumer. For models that are driven directly by a write API (such -as #GListStore), changes can be reported in response to uses of that -API. For models that represent remote data, changes should only be -made from a fresh mainloop dispatch. It is particularly not -permitted to make changes in response to a call to the #GListModel -consumer API. - -Stated another way: in general, it is assumed that code making a -series of accesses to the model via the API, without returning to the -mainloop, and without calling other code, will continue to view the -same contents of the model. - - - - - - - a #GListModel - - - - the position at which @list changed - - - - the number of items removed - - - - the number of items added - - - - - - This signal is emitted whenever items were added to or removed -from @list. At @position, @removed items were removed and @added -items were added in their place. - -Note: If @removed != @added, the positions of all later items -in the model change. - - - - - - the position at which @list changed - - - - the number of items removed - - - - the number of items added - - - - - - - The virtual function table for #GListModel. - - - parent #GTypeInterface - - - - - - - the #GType of the items contained in @list. - - - - - a #GListModel - - - - - - - - - - the number of items in @list. - - - - - a #GListModel - - - - - - - - - - the object at @position. - - - - - a #GListModel - - - - the position of the item to fetch - - - - - - - - #GListStore is a simple implementation of #GListModel that stores all -items in memory. - -It provides insertions, deletions, and lookups in logarithmic time -with a fast path for the common case of iterating the list linearly. - - - - Creates a new #GListStore with items of type @item_type. @item_type -must be a subclass of #GObject. - - - a new #GListStore - - - - - the #GType of items in the list - - - - - - Appends @item to @store. @item must be of type #GListStore:item-type. - -This function takes a ref on @item. - -Use g_list_store_splice() to append multiple items at the same time -efficiently. - - - - - - - a #GListStore - - - - the new item - - - - - - Looks up the given @item in the list store by looping over the items until -the first occurrence of @item. If @item was not found, then @position will -not be set, and this method will return %FALSE. - -If you need to compare the two items with a custom comparison function, use -g_list_store_find_with_equal_func() with a custom #GEqualFunc instead. - - - Whether @store contains @item. If it was found, @position will be -set to the position where @item occurred for the first time. - - - - - a #GListStore - - - - an item - - - - the first position of @item, if it was found. - - - - - - Looks up the given @item in the list store by looping over the items and -comparing them with @compare_func until the first occurrence of @item which -matches. If @item was not found, then @position will not be set, and this -method will return %FALSE. - - - Whether @store contains @item. If it was found, @position will be -set to the position where @item occurred for the first time. - - - - - a #GListStore - - - - an item - - - - A custom equality check function - - - - the first position of @item, if it was found. - - - - - - Inserts @item into @store at @position. @item must be of type -#GListStore:item-type or derived from it. @position must be smaller -than the length of the list, or equal to it to append. - -This function takes a ref on @item. - -Use g_list_store_splice() to insert multiple items at the same time -efficiently. - - - - - - - a #GListStore - - - - the position at which to insert the new item - - - - the new item - - - - - - Inserts @item into @store at a position to be determined by the -@compare_func. - -The list must already be sorted before calling this function or the -result is undefined. Usually you would approach this by only ever -inserting items by way of this function. - -This function takes a ref on @item. - - - the position at which @item was inserted - - - - - a #GListStore - - - - the new item - - - - pairwise comparison function for sorting - - - - user data for @compare_func - - - - - - Removes the item from @store that is at @position. @position must be -smaller than the current length of the list. - -Use g_list_store_splice() to remove multiple items at the same time -efficiently. - - - - - - - a #GListStore - - - - the position of the item that is to be removed - - - - - - Removes all items from @store. - - - - - - - a #GListStore - - - - - - Sort the items in @store according to @compare_func. - - - - - - - a #GListStore - - - - pairwise comparison function for sorting - - - - user data for @compare_func - - - - - - Changes @store by removing @n_removals items and adding @n_additions -items to it. @additions must contain @n_additions items of type -#GListStore:item-type. %NULL is not permitted. - -This function is more efficient than g_list_store_insert() and -g_list_store_remove(), because it only emits -#GListModel::items-changed once for the change. - -This function takes a ref on each item in @additions. - -The parameters @position and @n_removals must be correct (ie: -@position + @n_removals must be less than or equal to the length of -the list at the time this function is called). - - - - - - - a #GListStore - - - - the position at which to make the change - - - - the number of items to remove - - - - the items to add - - - - - - the number of items to add - - - - - - The type of items contained in this list store. Items must be -subclasses of #GObject. - - - - - - - - - - - Extends the #GIcon interface and adds the ability to -load icons from streams. - - - - Loads a loadable icon. For the asynchronous version of this function, -see g_loadable_icon_load_async(). - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - an integer. - - - - a location to store the type of the loaded -icon, %NULL to ignore. - - - - optional #GCancellable object, %NULL to -ignore. - - - - - - Loads an icon asynchronously. To finish this function, see -g_loadable_icon_load_finish(). For the synchronous, blocking -version of this function, see g_loadable_icon_load(). - - - - - - - a #GLoadableIcon. - - - - an integer. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous icon load started in g_loadable_icon_load_async(). - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - a #GAsyncResult. - - - - a location to store the type of the loaded - icon, %NULL to ignore. - - - - - - Loads a loadable icon. For the asynchronous version of this function, -see g_loadable_icon_load_async(). - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - an integer. - - - - a location to store the type of the loaded -icon, %NULL to ignore. - - - - optional #GCancellable object, %NULL to -ignore. - - - - - - Loads an icon asynchronously. To finish this function, see -g_loadable_icon_load_finish(). For the synchronous, blocking -version of this function, see g_loadable_icon_load(). - - - - - - - a #GLoadableIcon. - - - - an integer. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous icon load started in g_loadable_icon_load_async(). - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - a #GAsyncResult. - - - - a location to store the type of the loaded - icon, %NULL to ignore. - - - - - - - Interface for icons that can be loaded as a stream. - - - The parent interface. - - - - - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - an integer. - - - - a location to store the type of the loaded -icon, %NULL to ignore. - - - - optional #GCancellable object, %NULL to -ignore. - - - - - - - - - - - - - - a #GLoadableIcon. - - - - an integer. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GInputStream to read the icon from. - - - - - a #GLoadableIcon. - - - - a #GAsyncResult. - - - - a location to store the type of the loaded - icon, %NULL to ignore. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for memory usage monitoring functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The menu item attribute which holds the action name of the item. Action -names are namespaced with an identifier for the action group in which the -action resides. For example, "win." for window-specific actions and "app." -for application-wide actions. - -See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute(). - - - - - The menu item attribute that holds the namespace for all action names in -menus that are linked from this item. - - - - - The menu item attribute which holds the icon of the item. - -The icon is stored in the format returned by g_icon_serialize(). - -This attribute is intended only to represent 'noun' icons such as -favicons for a webpage, or application icons. It should not be used -for 'verbs' (ie: stock icons). - - - - - - - - - - - - - - - - - - - - - - - - - - The menu item attribute which holds the label of the item. - - - - - The menu item attribute which holds the target with which the item's action -will be activated. - -See also g_menu_item_set_action_and_target() - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the link that associates a menu item with a section. The linked -menu will usually be shown in place of the menu item, using the item's label -as a header. - -See also g_menu_item_set_link(). - - - - - The name of the link that associates a menu item with a submenu. - -See also g_menu_item_set_link(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GMemoryInputStream is a class for using arbitrary -memory chunks as input for GIO streaming input operations. - -As of GLib 2.34, #GMemoryInputStream implements -#GPollableInputStream. - - - - - Creates a new empty #GMemoryInputStream. - - - a new #GInputStream - - - - - Creates a new #GMemoryInputStream with data from the given @bytes. - - - new #GInputStream read from @bytes - - - - - a #GBytes - - - - - - Creates a new #GMemoryInputStream with data in memory of a given size. - - - new #GInputStream read from @data of @len bytes. - - - - - input data - - - - - - length of the data, may be -1 if @data is a nul-terminated string - - - - function that is called to free @data, or %NULL - - - - - - Appends @bytes to data that can be read from the input stream. - - - - - - - a #GMemoryInputStream - - - - input data - - - - - - Appends @data to data that can be read from the input stream - - - - - - - a #GMemoryInputStream - - - - input data - - - - - - length of the data, may be -1 if @data is a nul-terminated string - - - - function that is called to free @data, or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GMemoryMonitor will monitor system memory and suggest to the application -when to free memory so as to leave more room for other applications. -It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) -([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)). - -There is also an implementation for use inside Flatpak sandboxes. - -Possible actions to take when the signal is received are: -- Free caches -- Save files that haven't been looked at in a while to disk, ready to be reopened when needed -- Run a garbage collection cycle -- Try and compress fragmented allocations -- Exit on idle if the process has no reason to stay around - -See #GMemoryMonitorWarningLevel for details on the various warning levels. - -|[<!-- language="C" --> -static void -warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) -{ - g_debug ("Warning level: %d", level); - if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) - drop_caches (); -} - -static GMemoryMonitor * -monitor_low_memory (void) -{ - GMemoryMonitor *m; - m = g_memory_monitor_dup_default (); - g_signal_connect (G_OBJECT (m), "low-memory-warning", - G_CALLBACK (warning_cb), NULL); - return m; -} -]| - -Don't forget to disconnect the #GMemoryMonitor::low-memory-warning -signal, and unref the #GMemoryMonitor itself when exiting. - - - - Gets a reference to the default #GMemoryMonitor for the system. - - - a new reference to the default #GMemoryMonitor - - - - - - - - - - - - - - - - - - - Emitted when the system is running low on free memory. The signal -handler should then take the appropriate action depending on the -warning level. See the #GMemoryMonitorWarningLevel documentation for -details. - - - - - - the #GMemoryMonitorWarningLevel warning level - - - - - - - The virtual function table for #GMemoryMonitor. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - Memory availability warning levels. - -Note that because new values might be added, it is recommended that applications check -#GMemoryMonitorWarningLevel as ranges, for example: -|[<!-- language="C" --> -if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) - drop_caches (); -]| - - Memory on the device is low, processes - should free up unneeded resources (for example, in-memory caches) so they can - be used elsewhere. - - - Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW - but the device has even less free memory, so processes should try harder to free - up unneeded resources. If your process does not need to stay running, it is a - good time for it to quit. - - - The system will soon start terminating - processes to reclaim memory, including background processes. - - - - #GMemoryOutputStream is a class for using arbitrary -memory chunks as output for GIO streaming output operations. - -As of GLib 2.34, #GMemoryOutputStream trivially implements -#GPollableOutputStream: it always polls as ready. - - - - - Creates a new #GMemoryOutputStream. - -In most cases this is not the function you want. See -g_memory_output_stream_new_resizable() instead. - -If @data is non-%NULL, the stream will use that for its internal storage. - -If @realloc_fn is non-%NULL, it will be used for resizing the internal -storage when necessary and the stream will be considered resizable. -In that case, the stream will start out being (conceptually) empty. -@size is used only as a hint for how big @data is. Specifically, -seeking to the end of a newly-created stream will seek to zero, not -@size. Seeking past the end of the stream and then writing will -introduce a zero-filled gap. - -If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to -the end will seek to @size exactly. Writing past the end will give -an 'out of space' error. Attempting to seek past the end will fail. -Unlike the resizable case, seeking to an offset within the stream and -writing will preserve the bytes passed in as @data before that point -and will return them as part of g_memory_output_stream_steal_data(). -If you intend to seek you should probably therefore ensure that @data -is properly initialised. - -It is probably only meaningful to provide @data and @size in the case -that you want a fixed-sized stream. Put another way: if @realloc_fn -is non-%NULL then it makes most sense to give @data as %NULL and -@size as 0 (allowing #GMemoryOutputStream to do the initial -allocation for itself). - -|[<!-- language="C" --> -// a stream that can grow -stream = g_memory_output_stream_new (NULL, 0, realloc, free); - -// another stream that can grow -stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); - -// a fixed-size stream -data = malloc (200); -stream3 = g_memory_output_stream_new (data, 200, NULL, free); -]| - - - A newly created #GMemoryOutputStream object. - - - - - pointer to a chunk of memory to use, or %NULL - - - - the size of @data - - - - a function with realloc() semantics (like g_realloc()) - to be called when @data needs to be grown, or %NULL - - - - a function to be called on @data when the stream is - finalized, or %NULL - - - - - - Creates a new #GMemoryOutputStream, using g_realloc() and g_free() -for memory allocation. - - - - - - - Gets any loaded data from the @ostream. - -Note that the returned pointer may become invalid on the next -write or truncate operation on the stream. - - - pointer to the stream's data, or %NULL if the data - has been stolen - - - - - a #GMemoryOutputStream - - - - - - Returns the number of bytes from the start up to including the last -byte written in the stream that has not been truncated away. - - - the number of bytes written to the stream - - - - - a #GMemoryOutputStream - - - - - - Gets the size of the currently allocated data area (available from -g_memory_output_stream_get_data()). - -You probably don't want to use this function on resizable streams. -See g_memory_output_stream_get_data_size() instead. For resizable -streams the size returned by this function is an implementation -detail and may be change at any time in response to operations on the -stream. - -If the stream is fixed-sized (ie: no realloc was passed to -g_memory_output_stream_new()) then this is the maximum size of the -stream and further writes will return %G_IO_ERROR_NO_SPACE. - -In any case, if you want the number of bytes currently written to the -stream, use g_memory_output_stream_get_data_size(). - - - the number of bytes allocated for the data buffer - - - - - a #GMemoryOutputStream - - - - - - Returns data from the @ostream as a #GBytes. @ostream must be -closed before calling this function. - - - the stream's data - - - - - a #GMemoryOutputStream - - - - - - Gets any loaded data from the @ostream. Ownership of the data -is transferred to the caller; when no longer needed it must be -freed using the free function set in @ostream's -#GMemoryOutputStream:destroy-function property. - -@ostream must be closed before calling this function. - - - the stream's data, or %NULL if it has previously - been stolen - - - - - a #GMemoryOutputStream - - - - - - Pointer to buffer where data will be written. - - - - Size of data written to the buffer. - - - - Function called with the buffer as argument when the stream is destroyed. - - - - Function with realloc semantics called to enlarge the buffer. - - - - Current size of the data buffer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GMenu is a simple implementation of #GMenuModel. -You populate a #GMenu by adding #GMenuItem instances to it. - -There are some convenience functions to allow you to directly -add items (avoiding #GMenuItem) for the common cases. To add -a regular item, use g_menu_insert(). To add a section, use -g_menu_insert_section(). To add a submenu, use -g_menu_insert_submenu(). - - Creates a new #GMenu. - -The new menu has no items. - - - a new #GMenu - - - - - Convenience function for appending a normal menu item to the end of -@menu. Combine g_menu_item_new() and g_menu_insert_item() for a more -flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - the detailed action string, or %NULL - - - - - - Appends @item to the end of @menu. - -See g_menu_insert_item() for more information. - - - - - - - a #GMenu - - - - a #GMenuItem to append - - - - - - Convenience function for appending a section menu item to the end of -@menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a -more flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the section - - - - - - Convenience function for appending a submenu menu item to the end of -@menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a -more flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the submenu - - - - - - Marks @menu as frozen. - -After the menu is frozen, it is an error to attempt to make any -changes to it. In effect this means that the #GMenu API must no -longer be used. - -This function causes g_menu_model_is_mutable() to begin returning -%FALSE, which has some positive performance implications. - - - - - - - a #GMenu - - - - - - Convenience function for inserting a normal menu item into @menu. -Combine g_menu_item_new() and g_menu_insert_item() for a more flexible -alternative. - - - - - - - a #GMenu - - - - the position at which to insert the item - - - - the section label, or %NULL - - - - the detailed action string, or %NULL - - - - - - Inserts @item into @menu. - -The "insertion" is actually done by copying all of the attribute and -link values of @item and using them to form a new item within @menu. -As such, @item itself is not really inserted, but rather, a menu item -that is exactly the same as the one presently described by @item. - -This means that @item is essentially useless after the insertion -occurs. Any changes you make to it are ignored unless it is inserted -again (at which point its updated values will be copied). - -You should probably just free @item once you're done. - -There are many convenience functions to take care of common cases. -See g_menu_insert(), g_menu_insert_section() and -g_menu_insert_submenu() as well as "prepend" and "append" variants of -each of these functions. - - - - - - - a #GMenu - - - - the position at which to insert the item - - - - the #GMenuItem to insert - - - - - - Convenience function for inserting a section menu item into @menu. -Combine g_menu_item_new_section() and g_menu_insert_item() for a more -flexible alternative. - - - - - - - a #GMenu - - - - the position at which to insert the item - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the section - - - - - - Convenience function for inserting a submenu menu item into @menu. -Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more -flexible alternative. - - - - - - - a #GMenu - - - - the position at which to insert the item - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the submenu - - - - - - Convenience function for prepending a normal menu item to the start -of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more -flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - the detailed action string, or %NULL - - - - - - Prepends @item to the start of @menu. - -See g_menu_insert_item() for more information. - - - - - - - a #GMenu - - - - a #GMenuItem to prepend - - - - - - Convenience function for prepending a section menu item to the start -of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for -a more flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the section - - - - - - Convenience function for prepending a submenu menu item to the start -of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for -a more flexible alternative. - - - - - - - a #GMenu - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the submenu - - - - - - Removes an item from the menu. - -@position gives the index of the item to remove. - -It is an error if position is not in range the range from 0 to one -less than the number of items in the menu. - -It is not possible to remove items by identity since items are added -to the menu simply by copying their links and attributes (ie: -identity of the item itself is not preserved). - - - - - - - a #GMenu - - - - the position of the item to remove - - - - - - Removes all items in the menu. - - - - - - - a #GMenu - - - - - - - #GMenuAttributeIter is an opaque structure type. You must access it -using the functions below. - - - This function combines g_menu_attribute_iter_next() with -g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). - -First the iterator is advanced to the next (possibly first) attribute. -If that fails, then %FALSE is returned and there are no other -effects. - -If successful, @name and @value are set to the name and value of the -attribute that has just been advanced to. At this point, -g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will -return the same values again. - -The value returned in @name remains valid for as long as the iterator -remains at the current position. The value returned in @value must -be unreffed using g_variant_unref() when it is no longer in use. - - - %TRUE on success, or %FALSE if there is no additional - attribute - - - - - a #GMenuAttributeIter - - - - the type of the attribute - - - - the attribute value - - - - - - Gets the name of the attribute at the current iterator position, as -a string. - -The iterator is not advanced. - - - the name of the attribute - - - - - a #GMenuAttributeIter - - - - - - This function combines g_menu_attribute_iter_next() with -g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). - -First the iterator is advanced to the next (possibly first) attribute. -If that fails, then %FALSE is returned and there are no other -effects. - -If successful, @name and @value are set to the name and value of the -attribute that has just been advanced to. At this point, -g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will -return the same values again. - -The value returned in @name remains valid for as long as the iterator -remains at the current position. The value returned in @value must -be unreffed using g_variant_unref() when it is no longer in use. - - - %TRUE on success, or %FALSE if there is no additional - attribute - - - - - a #GMenuAttributeIter - - - - the type of the attribute - - - - the attribute value - - - - - - Gets the value of the attribute at the current iterator position. - -The iterator is not advanced. - - - the value of the current attribute - - - - - a #GMenuAttributeIter - - - - - - Attempts to advance the iterator to the next (possibly first) -attribute. - -%TRUE is returned on success, or %FALSE if there are no more -attributes. - -You must call this function when you first acquire the iterator -to advance it to the first attribute (and determine if the first -attribute exists at all). - - - %TRUE on success, or %FALSE when there are no more attributes - - - - - a #GMenuAttributeIter - - - - - - - - - - - - - - - - - - - - - %TRUE on success, or %FALSE if there is no additional - attribute - - - - - a #GMenuAttributeIter - - - - the type of the attribute - - - - the attribute value - - - - - - - - - - - #GMenuItem is an opaque structure type. You must access it using the -functions below. - - Creates a new #GMenuItem. - -If @label is non-%NULL it is used to set the "label" attribute of the -new item. - -If @detailed_action is non-%NULL it is used to set the "action" and -possibly the "target" attribute of the new item. See -g_menu_item_set_detailed_action() for more information. - - - a new #GMenuItem - - - - - the section label, or %NULL - - - - the detailed action string, or %NULL - - - - - - Creates a #GMenuItem as an exact copy of an existing menu item in a -#GMenuModel. - -@item_index must be valid (ie: be sure to call -g_menu_model_get_n_items() first). - - - a new #GMenuItem. - - - - - a #GMenuModel - - - - the index of an item in @model - - - - - - Creates a new #GMenuItem representing a section. - -This is a convenience API around g_menu_item_new() and -g_menu_item_set_section(). - -The effect of having one menu appear as a section of another is -exactly as it sounds: the items from @section become a direct part of -the menu that @menu_item is added to. - -Visual separation is typically displayed between two non-empty -sections. If @label is non-%NULL then it will be encorporated into -this visual indication. This allows for labeled subsections of a -menu. - -As a simple example, consider a typical "Edit" menu from a simple -program. It probably contains an "Undo" and "Redo" item, followed by -a separator, followed by "Cut", "Copy" and "Paste". - -This would be accomplished by creating three #GMenu instances. The -first would be populated with the "Undo" and "Redo" items, and the -second with the "Cut", "Copy" and "Paste" items. The first and -second menus would then be added as submenus of the third. In XML -format, this would look something like the following: -|[ -<menu id='edit-menu'> - <section> - <item label='Undo'/> - <item label='Redo'/> - </section> - <section> - <item label='Cut'/> - <item label='Copy'/> - <item label='Paste'/> - </section> -</menu> -]| - -The following example is exactly equivalent. It is more illustrative -of the exact relationship between the menus and items (keeping in -mind that the 'link' element defines a new menu that is linked to the -containing one). The style of the second example is more verbose and -difficult to read (and therefore not recommended except for the -purpose of understanding what is really going on). -|[ -<menu id='edit-menu'> - <item> - <link name='section'> - <item label='Undo'/> - <item label='Redo'/> - </link> - </item> - <item> - <link name='section'> - <item label='Cut'/> - <item label='Copy'/> - <item label='Paste'/> - </link> - </item> -</menu> -]| - - - a new #GMenuItem - - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the section - - - - - - Creates a new #GMenuItem representing a submenu. - -This is a convenience API around g_menu_item_new() and -g_menu_item_set_submenu(). - - - a new #GMenuItem - - - - - the section label, or %NULL - - - - a #GMenuModel with the items of the submenu - - - - - - Queries the named @attribute on @menu_item. - -If the attribute exists and matches the #GVariantType corresponding -to @format_string then @format_string is used to deconstruct the -value into the positional parameters and %TRUE is returned. - -If the attribute does not exist, or it does exist but has the wrong -type, then the positional parameters are ignored and %FALSE is -returned. - - - %TRUE if the named attribute was found with the expected - type - - - - - a #GMenuItem - - - - the attribute name to query - - - - a #GVariant format string - - - - positional parameters, as per @format_string - - - - - - Queries the named @attribute on @menu_item. - -If @expected_type is specified and the attribute does not have this -type, %NULL is returned. %NULL is also returned if the attribute -simply does not exist. - - - the attribute value, or %NULL - - - - - a #GMenuItem - - - - the attribute name to query - - - - the expected type of the attribute - - - - - - Queries the named @link on @menu_item. - - - the link, or %NULL - - - - - a #GMenuItem - - - - the link name to query - - - - - - Sets or unsets the "action" and "target" attributes of @menu_item. - -If @action is %NULL then both the "action" and "target" attributes -are unset (and @format_string is ignored along with the positional -parameters). - -If @action is non-%NULL then the "action" attribute is set. -@format_string is then inspected. If it is non-%NULL then the proper -position parameters are collected to create a #GVariant instance to -use as the target value. If it is %NULL then the positional -parameters are ignored and the "target" attribute is unset. - -See also g_menu_item_set_action_and_target_value() for an equivalent -call that directly accepts a #GVariant. See -g_menu_item_set_detailed_action() for a more convenient version that -works with string-typed targets. - -See also g_menu_item_set_action_and_target_value() for a -description of the semantics of the action and target attributes. - - - - - - - a #GMenuItem - - - - the name of the action for this item - - - - a GVariant format string - - - - positional parameters, as per @format_string - - - - - - Sets or unsets the "action" and "target" attributes of @menu_item. - -If @action is %NULL then both the "action" and "target" attributes -are unset (and @target_value is ignored). - -If @action is non-%NULL then the "action" attribute is set. The -"target" attribute is then set to the value of @target_value if it is -non-%NULL or unset otherwise. - -Normal menu items (ie: not submenu, section or other custom item -types) are expected to have the "action" attribute set to identify -the action that they are associated with. The state type of the -action help to determine the disposition of the menu item. See -#GAction and #GActionGroup for an overview of actions. - -In general, clicking on the menu item will result in activation of -the named action with the "target" attribute given as the parameter -to the action invocation. If the "target" attribute is not set then -the action is invoked with no parameter. - -If the action has no state then the menu item is usually drawn as a -plain menu item (ie: with no additional decoration). - -If the action has a boolean state then the menu item is usually drawn -as a toggle menu item (ie: with a checkmark or equivalent -indication). The item should be marked as 'toggled' or 'checked' -when the boolean state is %TRUE. - -If the action has a string state then the menu item is usually drawn -as a radio menu item (ie: with a radio bullet or equivalent -indication). The item should be marked as 'selected' when the string -state is equal to the value of the @target property. - -See g_menu_item_set_action_and_target() or -g_menu_item_set_detailed_action() for two equivalent calls that are -probably more convenient for most uses. - - - - - - - a #GMenuItem - - - - the name of the action for this item - - - - a #GVariant to use as the action target - - - - - - Sets or unsets an attribute on @menu_item. - -The attribute to set or unset is specified by @attribute. This -can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, -%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom -attribute name. -Attribute names are restricted to lowercase characters, numbers -and '-'. Furthermore, the names must begin with a lowercase character, -must not end with a '-', and must not contain consecutive dashes. - -If @format_string is non-%NULL then the proper position parameters -are collected to create a #GVariant instance to use as the attribute -value. If it is %NULL then the positional parameterrs are ignored -and the named attribute is unset. - -See also g_menu_item_set_attribute_value() for an equivalent call -that directly accepts a #GVariant. - - - - - - - a #GMenuItem - - - - the attribute to set - - - - a #GVariant format string, or %NULL - - - - positional parameters, as per @format_string - - - - - - Sets or unsets an attribute on @menu_item. - -The attribute to set or unset is specified by @attribute. This -can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, -%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom -attribute name. -Attribute names are restricted to lowercase characters, numbers -and '-'. Furthermore, the names must begin with a lowercase character, -must not end with a '-', and must not contain consecutive dashes. - -must consist only of lowercase -ASCII characters, digits and '-'. - -If @value is non-%NULL then it is used as the new value for the -attribute. If @value is %NULL then the attribute is unset. If -the @value #GVariant is floating, it is consumed. - -See also g_menu_item_set_attribute() for a more convenient way to do -the same. - - - - - - - a #GMenuItem - - - - the attribute to set - - - - a #GVariant to use as the value, or %NULL - - - - - - Sets the "action" and possibly the "target" attribute of @menu_item. - -The format of @detailed_action is the same format parsed by -g_action_parse_detailed_name(). - -See g_menu_item_set_action_and_target() or -g_menu_item_set_action_and_target_value() for more flexible (but -slightly less convenient) alternatives. - -See also g_menu_item_set_action_and_target_value() for a description of -the semantics of the action and target attributes. - - - - - - - a #GMenuItem - - - - the "detailed" action string - - - - - - Sets (or unsets) the icon on @menu_item. - -This call is the same as calling g_icon_serialize() and using the -result as the value to g_menu_item_set_attribute_value() for -%G_MENU_ATTRIBUTE_ICON. - -This API is only intended for use with "noun" menu items; things like -bookmarks or applications in an "Open With" menu. Don't use it on -menu items corresponding to verbs (eg: stock icons for 'Save' or -'Quit'). - -If @icon is %NULL then the icon is unset. - - - - - - - a #GMenuItem - - - - a #GIcon, or %NULL - - - - - - Sets or unsets the "label" attribute of @menu_item. - -If @label is non-%NULL it is used as the label for the menu item. If -it is %NULL then the label attribute is unset. - - - - - - - a #GMenuItem - - - - the label to set, or %NULL to unset - - - - - - Creates a link from @menu_item to @model if non-%NULL, or unsets it. - -Links are used to establish a relationship between a particular menu -item and another menu. For example, %G_MENU_LINK_SUBMENU is used to -associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION -is used to create a section. Other types of link can be used, but there -is no guarantee that clients will be able to make sense of them. -Link types are restricted to lowercase characters, numbers -and '-'. Furthermore, the names must begin with a lowercase character, -must not end with a '-', and must not contain consecutive dashes. - - - - - - - a #GMenuItem - - - - type of link to establish or unset - - - - the #GMenuModel to link to (or %NULL to unset) - - - - - - Sets or unsets the "section" link of @menu_item to @section. - -The effect of having one menu appear as a section of another is -exactly as it sounds: the items from @section become a direct part of -the menu that @menu_item is added to. See g_menu_item_new_section() -for more information about what it means for a menu item to be a -section. - - - - - - - a #GMenuItem - - - - a #GMenuModel, or %NULL - - - - - - Sets or unsets the "submenu" link of @menu_item to @submenu. - -If @submenu is non-%NULL, it is linked to. If it is %NULL then the -link is unset. - -The effect of having one menu appear as a submenu of another is -exactly as it sounds. - - - - - - - a #GMenuItem - - - - a #GMenuModel, or %NULL - - - - - - - #GMenuLinkIter is an opaque structure type. You must access it using -the functions below. - - - This function combines g_menu_link_iter_next() with -g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). - -First the iterator is advanced to the next (possibly first) link. -If that fails, then %FALSE is returned and there are no other effects. - -If successful, @out_link and @value are set to the name and #GMenuModel -of the link that has just been advanced to. At this point, -g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the -same values again. - -The value returned in @out_link remains valid for as long as the iterator -remains at the current position. The value returned in @value must -be unreffed using g_object_unref() when it is no longer in use. - - - %TRUE on success, or %FALSE if there is no additional link - - - - - a #GMenuLinkIter - - - - the name of the link - - - - the linked #GMenuModel - - - - - - Gets the name of the link at the current iterator position. - -The iterator is not advanced. - - - the type of the link - - - - - a #GMenuLinkIter - - - - - - This function combines g_menu_link_iter_next() with -g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). - -First the iterator is advanced to the next (possibly first) link. -If that fails, then %FALSE is returned and there are no other effects. - -If successful, @out_link and @value are set to the name and #GMenuModel -of the link that has just been advanced to. At this point, -g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the -same values again. - -The value returned in @out_link remains valid for as long as the iterator -remains at the current position. The value returned in @value must -be unreffed using g_object_unref() when it is no longer in use. - - - %TRUE on success, or %FALSE if there is no additional link - - - - - a #GMenuLinkIter - - - - the name of the link - - - - the linked #GMenuModel - - - - - - Gets the linked #GMenuModel at the current iterator position. - -The iterator is not advanced. - - - the #GMenuModel that is linked to - - - - - a #GMenuLinkIter - - - - - - Attempts to advance the iterator to the next (possibly first) -link. - -%TRUE is returned on success, or %FALSE if there are no more links. - -You must call this function when you first acquire the iterator to -advance it to the first link (and determine if the first link exists -at all). - - - %TRUE on success, or %FALSE when there are no more links - - - - - a #GMenuLinkIter - - - - - - - - - - - - - - - - - - - - - %TRUE on success, or %FALSE if there is no additional link - - - - - a #GMenuLinkIter - - - - the name of the link - - - - the linked #GMenuModel - - - - - - - - - - - #GMenuModel represents the contents of a menu -- an ordered list of -menu items. The items are associated with actions, which can be -activated through them. Items can be grouped in sections, and may -have submenus associated with them. Both items and sections usually -have some representation data, such as labels or icons. The type of -the associated action (ie whether it is stateful, and what kind of -state it has) can influence the representation of the item. - -The conceptual model of menus in #GMenuModel is hierarchical: -sections and submenus are again represented by #GMenuModels. -Menus themselves do not define their own roles. Rather, the role -of a particular #GMenuModel is defined by the item that references -it (or, in the case of the 'root' menu, is defined by the context -in which it is used). - -As an example, consider the visible portions of this menu: - -## An example menu # {#menu-example} - -![](menu-example.png) - -There are 8 "menus" visible in the screenshot: one menubar, two -submenus and 5 sections: - -- the toplevel menubar (containing 4 items) -- the View submenu (containing 3 sections) -- the first section of the View submenu (containing 2 items) -- the second section of the View submenu (containing 1 item) -- the final section of the View submenu (containing 1 item) -- the Highlight Mode submenu (containing 2 sections) -- the Sources section (containing 2 items) -- the Markup section (containing 2 items) - -The [example][menu-model] illustrates the conceptual connection between -these 8 menus. Each large block in the figure represents a menu and the -smaller blocks within the large block represent items in that menu. Some -items contain references to other menus. - -## A menu example # {#menu-model} - -![](menu-model.png) - -Notice that the separators visible in the [example][menu-example] -appear nowhere in the [menu model][menu-model]. This is because -separators are not explicitly represented in the menu model. Instead, -a separator is inserted between any two non-empty sections of a menu. -Section items can have labels just like any other item. In that case, -a display system may show a section header instead of a separator. - -The motivation for this abstract model of application controls is -that modern user interfaces tend to make these controls available -outside the application. Examples include global menus, jumplists, -dash boards, etc. To support such uses, it is necessary to 'export' -information about actions and their representation in menus, which -is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] -and the [GMenuModel exporter][gio-GMenuModel-exporter] do for -#GActionGroup and #GMenuModel. The client-side counterparts to -make use of the exported information are #GDBusActionGroup and -#GDBusMenuModel. - -The API of #GMenuModel is very generic, with iterators for the -attributes and links of an item, see g_menu_model_iterate_item_attributes() -and g_menu_model_iterate_item_links(). The 'standard' attributes and -link types have predefined names: %G_MENU_ATTRIBUTE_LABEL, -%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION -and %G_MENU_LINK_SUBMENU. - -Items in a #GMenuModel represent active controls if they refer to -an action that can get activated when the user interacts with the -menu item. The reference to the action is encoded by the string id -in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely -identifies an action in an action group. Which action group(s) provide -actions depends on the context in which the menu model is used. -E.g. when the model is exported as the application menu of a -#GtkApplication, actions can be application-wide or window-specific -(and thus come from two different action groups). By convention, the -application-wide actions have names that start with "app.", while the -names of window-specific actions start with "win.". - -While a wide variety of stateful actions is possible, the following -is the minimum that is expected to be supported by all users of exported -menu information: -- an action with no parameter type and no state -- an action with no parameter type and boolean state -- an action with string parameter type and string state - -## Stateless - -A stateless action typically corresponds to an ordinary menu item. - -Selecting such a menu item will activate the action (with no parameter). - -## Boolean State - -An action with a boolean state will most typically be used with a "toggle" -or "switch" menu item. The state can be set directly, but activating the -action (with no parameter) results in the state being toggled. - -Selecting a toggle menu item will activate the action. The menu item should -be rendered as "checked" when the state is true. - -## String Parameter and State - -Actions with string parameters and state will most typically be used to -represent an enumerated choice over the items available for a group of -radio menu items. Activating the action with a string parameter is -equivalent to setting that parameter as the state. - -Radio menu items, in addition to being associated with the action, will -have a target value. Selecting that menu item will result in activation -of the action with the target value as the parameter. The menu item should -be rendered as "selected" when the state of the action is equal to the -target value of the menu item. - - - Queries the item at position @item_index in @model for the attribute -specified by @attribute. - -If @expected_type is non-%NULL then it specifies the expected type of -the attribute. If it is %NULL then any type will be accepted. - -If the attribute exists and matches @expected_type (or if the -expected type is unspecified) then the value is returned. - -If the attribute does not exist, or does not match the expected type -then %NULL is returned. - - - the value of the attribute - - - - - a #GMenuModel - - - - the index of the item - - - - the attribute to query - - - - the expected type of the attribute, or - %NULL - - - - - - Gets all the attributes associated with the item in the menu model. - - - - - - - the #GMenuModel to query - - - - The #GMenuItem to query - - - - Attributes on the item - - - - - - - - - Queries the item at position @item_index in @model for the link -specified by @link. - -If the link exists, the linked #GMenuModel is returned. If the link -does not exist, %NULL is returned. - - - the linked #GMenuModel, or %NULL - - - - - a #GMenuModel - - - - the index of the item - - - - the link to query - - - - - - Gets all the links associated with the item in the menu model. - - - - - - - the #GMenuModel to query - - - - The #GMenuItem to query - - - - Links from the item - - - - - - - - - Query the number of items in @model. - - - the number of items - - - - - a #GMenuModel - - - - - - Queries if @model is mutable. - -An immutable #GMenuModel will never emit the #GMenuModel::items-changed -signal. Consumers of the model may make optimisations accordingly. - - - %TRUE if the model is mutable (ie: "items-changed" may be - emitted). - - - - - a #GMenuModel - - - - - - Creates a #GMenuAttributeIter to iterate over the attributes of -the item at position @item_index in @model. - -You must free the iterator with g_object_unref() when you are done. - - - a new #GMenuAttributeIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - Creates a #GMenuLinkIter to iterate over the links of the item at -position @item_index in @model. - -You must free the iterator with g_object_unref() when you are done. - - - a new #GMenuLinkIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - Queries item at position @item_index in @model for the attribute -specified by @attribute. - -If the attribute exists and matches the #GVariantType corresponding -to @format_string then @format_string is used to deconstruct the -value into the positional parameters and %TRUE is returned. - -If the attribute does not exist, or it does exist but has the wrong -type, then the positional parameters are ignored and %FALSE is -returned. - -This function is a mix of g_menu_model_get_item_attribute_value() and -g_variant_get(), followed by a g_variant_unref(). As such, -@format_string must make a complete copy of the data (since the -#GVariant may go away after the call to g_variant_unref()). In -particular, no '&' characters are allowed in @format_string. - - - %TRUE if the named attribute was found with the expected - type - - - - - a #GMenuModel - - - - the index of the item - - - - the attribute to query - - - - a #GVariant format string - - - - positional parameters, as per @format_string - - - - - - Queries the item at position @item_index in @model for the attribute -specified by @attribute. - -If @expected_type is non-%NULL then it specifies the expected type of -the attribute. If it is %NULL then any type will be accepted. - -If the attribute exists and matches @expected_type (or if the -expected type is unspecified) then the value is returned. - -If the attribute does not exist, or does not match the expected type -then %NULL is returned. - - - the value of the attribute - - - - - a #GMenuModel - - - - the index of the item - - - - the attribute to query - - - - the expected type of the attribute, or - %NULL - - - - - - Queries the item at position @item_index in @model for the link -specified by @link. - -If the link exists, the linked #GMenuModel is returned. If the link -does not exist, %NULL is returned. - - - the linked #GMenuModel, or %NULL - - - - - a #GMenuModel - - - - the index of the item - - - - the link to query - - - - - - Query the number of items in @model. - - - the number of items - - - - - a #GMenuModel - - - - - - Queries if @model is mutable. - -An immutable #GMenuModel will never emit the #GMenuModel::items-changed -signal. Consumers of the model may make optimisations accordingly. - - - %TRUE if the model is mutable (ie: "items-changed" may be - emitted). - - - - - a #GMenuModel - - - - - - Requests emission of the #GMenuModel::items-changed signal on @model. - -This function should never be called except by #GMenuModel -subclasses. Any other calls to this function will very likely lead -to a violation of the interface of the model. - -The implementation should update its internal representation of the -menu before emitting the signal. The implementation should further -expect to receive queries about the new state of the menu (and -particularly added menu items) while signal handlers are running. - -The implementation must dispatch this call directly from a mainloop -entry and not in response to calls -- particularly those from the -#GMenuModel API. Said another way: the menu must not change while -user code is running without returning to the mainloop. - - - - - - - a #GMenuModel - - - - the position of the change - - - - the number of items removed - - - - the number of items added - - - - - - Creates a #GMenuAttributeIter to iterate over the attributes of -the item at position @item_index in @model. - -You must free the iterator with g_object_unref() when you are done. - - - a new #GMenuAttributeIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - Creates a #GMenuLinkIter to iterate over the links of the item at -position @item_index in @model. - -You must free the iterator with g_object_unref() when you are done. - - - a new #GMenuLinkIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - - - - - - - Emitted when a change has occured to the menu. - -The only changes that can occur to a menu is that items are removed -or added. Items may not change (except by being removed and added -back in the same location). This signal is capable of describing -both of those changes (at the same time). - -The signal means that starting at the index @position, @removed -items were removed and @added items were added in their place. If -@removed is zero then only items were added. If @added is zero -then only items were removed. - -As an example, if the menu contains items a, b, c, d (in that -order) and the signal (2, 1, 3) occurs then the new composition of -the menu will be a, b, _, _, _, d (with each _ representing some -new item). - -Signal handlers may query the model (particularly the added items) -and expect to see the results of the modification that is being -reported. The signal is emitted after the modification. - - - - - - the position of the change - - - - the number of items removed - - - - the number of items added - - - - - - - - - - - - - - - %TRUE if the model is mutable (ie: "items-changed" may be - emitted). - - - - - a #GMenuModel - - - - - - - - - - the number of items - - - - - a #GMenuModel - - - - - - - - - - - - - - the #GMenuModel to query - - - - The #GMenuItem to query - - - - Attributes on the item - - - - - - - - - - - - - a new #GMenuAttributeIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - - - - - the value of the attribute - - - - - a #GMenuModel - - - - the index of the item - - - - the attribute to query - - - - the expected type of the attribute, or - %NULL - - - - - - - - - - - - - - the #GMenuModel to query - - - - The #GMenuItem to query - - - - Links from the item - - - - - - - - - - - - - a new #GMenuLinkIter - - - - - a #GMenuModel - - - - the index of the item - - - - - - - - - - the linked #GMenuModel, or %NULL - - - - - a #GMenuModel - - - - the index of the item - - - - the link to query - - - - - - - - - - - The #GMount interface represents user-visible mounts. Note, when -porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. - -#GMount is a "mounted" filesystem that you can access. Mounted is in -quotes because it's not the same as a unix mount, it might be a gvfs -mount, but you can still access the files on it if you use GIO. Might or -might not be related to a volume object. - -Unmounting a #GMount instance is an asynchronous operation. For -more information about asynchronous operations, see #GAsyncResult -and #GTask. To unmount a #GMount instance, first call -g_mount_unmount_with_operation() with (at least) the #GMount instance and a -#GAsyncReadyCallback. The callback will be fired when the -operation has resolved (either with success or failure), and a -#GAsyncResult structure will be passed to the callback. That -callback should then call g_mount_unmount_with_operation_finish() with the #GMount -and the #GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_mount_unmount_with_operation_finish() -is called, then it will be filled with any error information. - - - Checks if @mount can be ejected. - - - %TRUE if the @mount can be ejected. - - - - - a #GMount. - - - - - - Checks if @mount can be unmounted. - - - %TRUE if the @mount can be unmounted. - - - - - a #GMount. - - - - - - - - - - - - - - - - - Ejects a mount. This is an asynchronous operation, and is -finished by calling g_mount_eject_finish() with the @mount -and #GAsyncResult data returned in the @callback. - Use g_mount_eject_with_operation() instead. - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_mount_eject_with_operation_finish() instead. - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Ejects a mount. This is an asynchronous operation, and is -finished by calling g_mount_eject_with_operation_finish() with the @mount -and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Gets the default location of @mount. The default location of the given -@mount is a path that reflects the main entry point for the user (e.g. -the home directory, or the root of the volume). - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the drive for the @mount. - -This is a convenience method for getting the #GVolume and then -using that object to get the #GDrive. - - - a #GDrive or %NULL if @mount is not - associated with a volume or a drive. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the icon for @mount. - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the name of @mount. - - - the name for the given @mount. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - Gets the root directory on @mount. - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the sort key for @mount, if any. - - - Sorting key for @mount or %NULL if no such key is available. - - - - - A #GMount. - - - - - - Gets the symbolic icon for @mount. - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the UUID for the @mount. The reference is typically based on -the file system UUID for the mount in question and should be -considered an opaque string. Returns %NULL if there is no UUID -available. - - - the UUID for @mount or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - Gets the volume for the @mount. - - - a #GVolume or %NULL if @mount is not - associated with a volume. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Tries to guess the type of content stored on @mount. Returns one or -more textual identifiers of well-known content types (typically -prefixed with "x-content/"), e.g. x-content/image-dcf for camera -memory cards. See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on x-content types. - -This is an asynchronous operation (see -g_mount_guess_content_type_sync() for the synchronous version), and -is finished by calling g_mount_guess_content_type_finish() with the -@mount and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback - - - - user data passed to @callback - - - - - - Finishes guessing content types of @mount. If any errors occurred -during the operation, @error will be set to contain the errors and -%FALSE will be returned. In particular, you may get an -%G_IO_ERROR_NOT_SUPPORTED if the mount does not support content -guessing. - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - a #GAsyncResult - - - - - - Tries to guess the type of content stored on @mount. Returns one or -more textual identifiers of well-known content types (typically -prefixed with "x-content/"), e.g. x-content/image-dcf for camera -memory cards. See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on x-content types. - -This is a synchronous operation and as such may block doing IO; -see g_mount_guess_content_type() for the asynchronous version. - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - - - - - - - - - - - - - - Remounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_remount_finish() with the @mount -and #GAsyncResults data returned in the @callback. - -Remounting is useful when some setting affecting the operation -of the volume has been changed, as these may need a remount to -take affect. While this is semantically equivalent with unmounting -and then remounting not all backends might need to actually be -unmounted. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes remounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully remounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Unmounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_unmount_finish() with the @mount -and #GAsyncResult data returned in the @callback. - Use g_mount_unmount_with_operation() instead. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes unmounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_mount_unmount_with_operation_finish() instead. - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Unmounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_unmount_with_operation_finish() with the @mount -and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes unmounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - Checks if @mount can be ejected. - - - %TRUE if the @mount can be ejected. - - - - - a #GMount. - - - - - - Checks if @mount can be unmounted. - - - %TRUE if the @mount can be unmounted. - - - - - a #GMount. - - - - - - Ejects a mount. This is an asynchronous operation, and is -finished by calling g_mount_eject_finish() with the @mount -and #GAsyncResult data returned in the @callback. - Use g_mount_eject_with_operation() instead. - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_mount_eject_with_operation_finish() instead. - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Ejects a mount. This is an asynchronous operation, and is -finished by calling g_mount_eject_with_operation_finish() with the @mount -and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes ejecting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Gets the default location of @mount. The default location of the given -@mount is a path that reflects the main entry point for the user (e.g. -the home directory, or the root of the volume). - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the drive for the @mount. - -This is a convenience method for getting the #GVolume and then -using that object to get the #GDrive. - - - a #GDrive or %NULL if @mount is not - associated with a volume or a drive. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the icon for @mount. - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the name of @mount. - - - the name for the given @mount. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - Gets the root directory on @mount. - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the sort key for @mount, if any. - - - Sorting key for @mount or %NULL if no such key is available. - - - - - A #GMount. - - - - - - Gets the symbolic icon for @mount. - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Gets the UUID for the @mount. The reference is typically based on -the file system UUID for the mount in question and should be -considered an opaque string. Returns %NULL if there is no UUID -available. - - - the UUID for @mount or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - Gets the volume for the @mount. - - - a #GVolume or %NULL if @mount is not - associated with a volume. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - Tries to guess the type of content stored on @mount. Returns one or -more textual identifiers of well-known content types (typically -prefixed with "x-content/"), e.g. x-content/image-dcf for camera -memory cards. See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on x-content types. - -This is an asynchronous operation (see -g_mount_guess_content_type_sync() for the synchronous version), and -is finished by calling g_mount_guess_content_type_finish() with the -@mount and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback - - - - user data passed to @callback - - - - - - Finishes guessing content types of @mount. If any errors occurred -during the operation, @error will be set to contain the errors and -%FALSE will be returned. In particular, you may get an -%G_IO_ERROR_NOT_SUPPORTED if the mount does not support content -guessing. - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - a #GAsyncResult - - - - - - Tries to guess the type of content stored on @mount. Returns one or -more textual identifiers of well-known content types (typically -prefixed with "x-content/"), e.g. x-content/image-dcf for camera -memory cards. See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on x-content types. - -This is a synchronous operation and as such may block doing IO; -see g_mount_guess_content_type() for the asynchronous version. - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - - - Determines if @mount is shadowed. Applications or libraries should -avoid displaying @mount in the user interface if it is shadowed. - -A mount is said to be shadowed if there exists one or more user -visible objects (currently #GMount objects) with a root that is -inside the root of @mount. - -One application of shadow mounts is when exposing a single file -system that is used to address several logical volumes. In this -situation, a #GVolumeMonitor implementation would create two -#GVolume objects (for example, one for the camera functionality of -the device and one for a SD card reader on the device) with -activation URIs `gphoto2://[usb:001,002]/store1/` -and `gphoto2://[usb:001,002]/store2/`. When the -underlying mount (with root -`gphoto2://[usb:001,002]/`) is mounted, said -#GVolumeMonitor implementation would create two #GMount objects -(each with their root matching the corresponding volume activation -root) that would shadow the original mount. - -The proxy monitor in GVfs 2.26 and later, automatically creates and -manage shadow mounts (and shadows the underlying mount) if the -activation root on a #GVolume is set. - - - %TRUE if @mount is shadowed. - - - - - A #GMount. - - - - - - Remounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_remount_finish() with the @mount -and #GAsyncResults data returned in the @callback. - -Remounting is useful when some setting affecting the operation -of the volume has been changed, as these may need a remount to -take affect. While this is semantically equivalent with unmounting -and then remounting not all backends might need to actually be -unmounted. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes remounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully remounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Increments the shadow count on @mount. Usually used by -#GVolumeMonitor implementations when creating a shadow mount for -@mount, see g_mount_is_shadowed() for more information. The caller -will need to emit the #GMount::changed signal on @mount manually. - - - - - - - A #GMount. - - - - - - Unmounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_unmount_finish() with the @mount -and #GAsyncResult data returned in the @callback. - Use g_mount_unmount_with_operation() instead. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes unmounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_mount_unmount_with_operation_finish() instead. - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Unmounts a mount. This is an asynchronous operation, and is -finished by calling g_mount_unmount_with_operation_finish() with the @mount -and #GAsyncResult data returned in the @callback. - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - Finishes unmounting a mount. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - Decrements the shadow count on @mount. Usually used by -#GVolumeMonitor implementations when destroying a shadow mount for -@mount, see g_mount_is_shadowed() for more information. The caller -will need to emit the #GMount::changed signal on @mount manually. - - - - - - - A #GMount. - - - - - - Emitted when the mount has been changed. - - - - - - This signal may be emitted when the #GMount is about to be -unmounted. - -This signal depends on the backend and is only emitted if -GIO was used to unmount. - - - - - - This signal is emitted when the #GMount have been -unmounted. If the recipient is holding references to the -object they should release them so the object can be -finalized. - - - - - - - Interface for implementing operations for mounts. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - - - the name for the given @mount. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - - - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - - - the UUID for @mount or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GMount. - - - - - - - - - - a #GVolume or %NULL if @mount is not - associated with a volume. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - - - a #GDrive or %NULL if @mount is not - associated with a volume or a drive. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - - - %TRUE if the @mount can be unmounted. - - - - - a #GMount. - - - - - - - - - - %TRUE if the @mount can be ejected. - - - - - a #GMount. - - - - - - - - - - - - - - a #GMount. - - - - flags affecting the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the mount was successfully remounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback - - - - user data passed to @callback - - - - - - - - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - a #GAsyncResult - - - - - - - - - - a %NULL-terminated array of content types or %NULL on error. - Caller should free this array with g_strfreev() when done with it. - - - - - - - a #GMount - - - - Whether to force a rescan of the content. - Otherwise a cached result will be used if available - - - - optional #GCancellable object, %NULL to ignore - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GMount. - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the mount was successfully unmounted. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GMount. - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to avoid - user interaction. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback, or %NULL. - - - - user data passed to @callback. - - - - - - - - - - %TRUE if the mount was successfully ejected. %FALSE otherwise. - - - - - a #GMount. - - - - a #GAsyncResult. - - - - - - - - - - a #GFile. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - - - Sorting key for @mount or %NULL if no such key is available. - - - - - A #GMount. - - - - - - - - - - a #GIcon. - The returned object should be unreffed with - g_object_unref() when no longer needed. - - - - - a #GMount. - - - - - - - - Flags used when mounting a mount. - - No flags set. - - - - #GMountOperation provides a mechanism for interacting with the user. -It can be used for authenticating mountable operations, such as loop -mounting files, hard drive partitions or server locations. It can -also be used to ask the user questions or show a list of applications -preventing unmount or eject operations from completing. - -Note that #GMountOperation is used for more than just #GMount -objects – for example it is also used in g_drive_start() and -g_drive_stop(). - -Users should instantiate a subclass of this that implements all the -various callbacks to show the required dialogs, such as -#GtkMountOperation. If no user interaction is desired (for example -when automounting filesystems at login time), usually %NULL can be -passed, see each method taking a #GMountOperation for details. - -The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. -[TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for -encrypting file containers, partitions or whole disks, typically used with Windows. -[VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various -improvements and auditing fixes. - - - Creates a new mount operation. - - - a #GMountOperation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Virtual implementation of #GMountOperation::ask-question. - - - - - - - a #GMountOperation - - - - string containing a message to display to the user - - - - an array of - strings for each possible choice - - - - - - - - Emits the #GMountOperation::reply signal. - - - - - - - a #GMountOperation - - - - a #GMountOperationResult - - - - - - Virtual implementation of #GMountOperation::show-processes. - - - - - - - a #GMountOperation - - - - string containing a message to display to the user - - - - an array of #GPid for processes blocking - the operation - - - - - - an array of - strings for each possible choice - - - - - - - - - - - - - - - - - - - - - - - - - - - - Check to see whether the mount operation is being used -for an anonymous user. - - - %TRUE if mount operation is anonymous. - - - - - a #GMountOperation. - - - - - - Gets a choice from the mount operation. - - - an integer containing an index of the user's choice from -the choice's list, or `0`. - - - - - a #GMountOperation. - - - - - - Gets the domain of the mount operation. - - - a string set to the domain. - - - - - a #GMountOperation. - - - - - - Check to see whether the mount operation is being used -for a TCRYPT hidden volume. - - - %TRUE if mount operation is for hidden volume. - - - - - a #GMountOperation. - - - - - - Check to see whether the mount operation is being used -for a TCRYPT system volume. - - - %TRUE if mount operation is for system volume. - - - - - a #GMountOperation. - - - - - - Gets a password from the mount operation. - - - a string containing the password within @op. - - - - - a #GMountOperation. - - - - - - Gets the state of saving passwords for the mount operation. - - - a #GPasswordSave flag. - - - - - a #GMountOperation. - - - - - - Gets a PIM from the mount operation. - - - The VeraCrypt PIM within @op. - - - - - a #GMountOperation. - - - - - - Get the user name from the mount operation. - - - a string containing the user name. - - - - - a #GMountOperation. - - - - - - Emits the #GMountOperation::reply signal. - - - - - - - a #GMountOperation - - - - a #GMountOperationResult - - - - - - Sets the mount operation to use an anonymous user if @anonymous is %TRUE. - - - - - - - a #GMountOperation. - - - - boolean value. - - - - - - Sets a default choice for the mount operation. - - - - - - - a #GMountOperation. - - - - an integer. - - - - - - Sets the mount operation's domain. - - - - - - - a #GMountOperation. - - - - the domain to set. - - - - - - Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. - - - - - - - a #GMountOperation. - - - - boolean value. - - - - - - Sets the mount operation to use a system volume if @system_volume is %TRUE. - - - - - - - a #GMountOperation. - - - - boolean value. - - - - - - Sets the mount operation's password to @password. - - - - - - - a #GMountOperation. - - - - password to set. - - - - - - Sets the state of saving passwords for the mount operation. - - - - - - - a #GMountOperation. - - - - a set of #GPasswordSave flags. - - - - - - Sets the mount operation's PIM to @pim. - - - - - - - a #GMountOperation. - - - - an unsigned integer. - - - - - - Sets the user name within @op to @username. - - - - - - - a #GMountOperation. - - - - input username. - - - - - - Whether to use an anonymous user when authenticating. - - - - The index of the user's choice when a question is asked during the -mount operation. See the #GMountOperation::ask-question signal. - - - - The domain to use for the mount operation. - - - - Whether the device to be unlocked is a TCRYPT hidden volume. -See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). - - - - Whether the device to be unlocked is a TCRYPT system volume. -In this context, a system volume is a volume with a bootloader -and operating system installed. This is only supported for Windows -operating systems. For further documentation, see -[the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html). - - - - The password that is used for authentication when carrying out -the mount operation. - - - - Determines if and how the password information should be saved. - - - - The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See -[the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). - - - - The user name that is used for authentication when carrying out -the mount operation. - - - - - - - - - - Emitted by the backend when e.g. a device becomes unavailable -while a mount operation is in progress. - -Implementations of GMountOperation should handle this signal -by dismissing open password dialogs. - - - - - - Emitted when a mount operation asks the user for a password. - -If the message contains a line break, the first line should be -presented as a heading. For example, it may be used as the -primary text in a #GtkMessageDialog. - - - - - - string containing a message to display to the user. - - - - string containing the default user name. - - - - string containing the default domain. - - - - a set of #GAskPasswordFlags. - - - - - - Emitted when asking the user a question and gives a list of -choices for the user to choose from. - -If the message contains a line break, the first line should be -presented as a heading. For example, it may be used as the -primary text in a #GtkMessageDialog. - - - - - - string containing a message to display to the user. - - - - an array of strings for each possible choice. - - - - - - - - Emitted when the user has replied to the mount operation. - - - - - - a #GMountOperationResult indicating how the request was handled - - - - - - Emitted when one or more processes are blocking an operation -e.g. unmounting/ejecting a #GMount or stopping a #GDrive. - -Note that this signal may be emitted several times to update the -list of blocking processes as processes close files. The -application should only respond with g_mount_operation_reply() to -the latest signal (setting #GMountOperation:choice to the choice -the user made). - -If the message contains a line break, the first line should be -presented as a heading. For example, it may be used as the -primary text in a #GtkMessageDialog. - - - - - - string containing a message to display to the user. - - - - an array of #GPid for processes - blocking the operation. - - - - - - an array of strings for each possible choice. - - - - - - - - Emitted when an unmount operation has been busy for more than some time -(typically 1.5 seconds). - -When unmounting or ejecting a volume, the kernel might need to flush -pending data in its buffers to the volume stable storage, and this operation -can take a considerable amount of time. This signal may be emitted several -times as long as the unmount operation is outstanding, and then one -last time when the operation is completed, with @bytes_left set to zero. - -Implementations of GMountOperation should handle this signal by -showing an UI notification, and then dismiss it, or show another notification -of completion, when @bytes_left reaches zero. - -If the message contains a line break, the first line should be -presented as a heading. For example, it may be used as the -primary text in a #GtkMessageDialog. - - - - - - string containing a mesage to display to the user - - - - the estimated time left before the operation completes, - in microseconds, or -1 - - - - the amount of bytes to be written before the operation - completes (or -1 if such amount is not known), or zero if the operation - is completed - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GMountOperation - - - - string containing a message to display to the user - - - - an array of - strings for each possible choice - - - - - - - - - - - - - - - - a #GMountOperation - - - - a #GMountOperationResult - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GMountOperation - - - - string containing a message to display to the user - - - - an array of #GPid for processes blocking - the operation - - - - - - an array of - strings for each possible choice - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GMountOperationResult is returned as a result when a request for -information is send by the mounting operation. - - The request was fulfilled and the - user specified data is now available - - - The user requested the mount operation - to be aborted - - - The request was unhandled (i.e. not - implemented) - - - - Flags used when an unmounting a mount. - - No flags set. - - - Unmount even if there are outstanding - file operations on the mount. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for network status monitoring functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A socket address of some unknown native type. - - - - Creates a new #GNativeSocketAddress for @native and @len. - - - a new #GNativeSocketAddress - - - - - a native address object - - - - the length of @native, in bytes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GNetworkAddress provides an easy way to resolve a hostname and -then attempt to connect to that host, handling the possibility of -multiple IP addresses and multiple address families. - -The enumeration results of resolved addresses *may* be cached as long -as this object is kept alive which may have unexpected results if -alive for too long. - -See #GSocketConnectable for an example of using the connectable -interface. - - - - Creates a new #GSocketConnectable for connecting to the given -@hostname and @port. - -Note that depending on the configuration of the machine, a -@hostname of `localhost` may refer to the IPv4 loopback address -only, or to both IPv4 and IPv6; use -g_network_address_new_loopback() to create a #GNetworkAddress that -is guaranteed to resolve to both addresses. - - - the new #GNetworkAddress - - - - - the hostname - - - - the port - - - - - - Creates a new #GSocketConnectable for connecting to the local host -over a loopback connection to the given @port. This is intended for -use in connecting to local services which may be running on IPv4 or -IPv6. - -The connectable will return IPv4 and IPv6 loopback addresses, -regardless of how the host resolves `localhost`. By contrast, -g_network_address_new() will often only return an IPv4 address when -resolving `localhost`, and an IPv6 address for `localhost6`. - -g_network_address_get_hostname() will always return `localhost` for -a #GNetworkAddress created with this constructor. - - - the new #GNetworkAddress - - - - - the port - - - - - - Creates a new #GSocketConnectable for connecting to the given -@hostname and @port. May fail and return %NULL in case -parsing @host_and_port fails. - -@host_and_port may be in any of a number of recognised formats; an IPv6 -address, an IPv4 address, or a domain name (in which case a DNS -lookup is performed). Quoting with [] is supported for all address -types. A port override may be specified in the usual way with a -colon. - -If no port is specified in @host_and_port then @default_port will be -used as the port number to connect to. - -In general, @host_and_port is expected to be provided by the user -(allowing them to give the hostname, and a port override if necessary) -and @default_port is expected to be provided by the application. - -(The port component of @host_and_port can also be specified as a -service name rather than as a numeric port, but this functionality -is deprecated, because it depends on the contents of /etc/services, -which is generally quite sparse on platforms other than Linux.) - - - the new - #GNetworkAddress, or %NULL on error - - - - - the hostname and optionally a port - - - - the default port if not in @host_and_port - - - - - - Creates a new #GSocketConnectable for connecting to the given -@uri. May fail and return %NULL in case parsing @uri fails. - -Using this rather than g_network_address_new() or -g_network_address_parse() allows #GSocketClient to determine -when to use application-specific proxy protocols. - - - the new - #GNetworkAddress, or %NULL on error - - - - - the hostname and optionally a port - - - - The default port if none is found in the URI - - - - - - Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, -depending on what @addr was created with. - - - @addr's hostname - - - - - a #GNetworkAddress - - - - - - Gets @addr's port number - - - @addr's port (which may be 0) - - - - - a #GNetworkAddress - - - - - - Gets @addr's scheme - - - @addr's scheme (%NULL if not built from URI) - - - - - a #GNetworkAddress - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The host's network connectivity state, as reported by #GNetworkMonitor. - - The host is not configured with a - route to the Internet; it may or may not be connected to a local - network. - - - The host is connected to a network, but - does not appear to be able to reach the full Internet, perhaps - due to upstream network problems. - - - The host is behind a captive portal and - cannot reach the full Internet. - - - The host is connected to a network, and - appears to be able to reach the full Internet. - - - - #GNetworkMonitor provides an easy-to-use cross-platform API -for monitoring network connectivity. On Linux, the available -implementations are based on the kernel's netlink interface and -on NetworkManager. - -There is also an implementation for use inside Flatpak sandboxes. - - - - Gets the default #GNetworkMonitor for the system. - - - a #GNetworkMonitor - - - - - Attempts to determine whether or not the host pointed to by -@connectable can be reached, without actually trying to connect to -it. - -This may return %TRUE even when #GNetworkMonitor:network-available -is %FALSE, if, for example, @monitor can determine that -@connectable refers to a host on a local network. - -If @monitor believes that an attempt to connect to @connectable -will succeed, it will return %TRUE. Otherwise, it will return -%FALSE and set @error to an appropriate error (such as -%G_IO_ERROR_HOST_UNREACHABLE). - -Note that although this does not attempt to connect to -@connectable, it may still block for a brief period of time (eg, -trying to do multicast DNS on the local network), so if you do not -want to block, you should use g_network_monitor_can_reach_async(). - - - %TRUE if @connectable is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - - - Asynchronously attempts to determine whether or not the host -pointed to by @connectable can be reached, without actually -trying to connect to it. - -For more details, see g_network_monitor_can_reach(). - -When the operation is finished, @callback will be called. -You can then call g_network_monitor_can_reach_finish() -to get the result of the operation. - - - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an async network connectivity test. -See g_network_monitor_can_reach_async(). - - - %TRUE if network is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - - - - Attempts to determine whether or not the host pointed to by -@connectable can be reached, without actually trying to connect to -it. - -This may return %TRUE even when #GNetworkMonitor:network-available -is %FALSE, if, for example, @monitor can determine that -@connectable refers to a host on a local network. - -If @monitor believes that an attempt to connect to @connectable -will succeed, it will return %TRUE. Otherwise, it will return -%FALSE and set @error to an appropriate error (such as -%G_IO_ERROR_HOST_UNREACHABLE). - -Note that although this does not attempt to connect to -@connectable, it may still block for a brief period of time (eg, -trying to do multicast DNS on the local network), so if you do not -want to block, you should use g_network_monitor_can_reach_async(). - - - %TRUE if @connectable is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - - - Asynchronously attempts to determine whether or not the host -pointed to by @connectable can be reached, without actually -trying to connect to it. - -For more details, see g_network_monitor_can_reach(). - -When the operation is finished, @callback will be called. -You can then call g_network_monitor_can_reach_finish() -to get the result of the operation. - - - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an async network connectivity test. -See g_network_monitor_can_reach_async(). - - - %TRUE if network is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GAsyncResult - - - - - - Gets a more detailed networking state than -g_network_monitor_get_network_available(). - -If #GNetworkMonitor:network-available is %FALSE, then the -connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. - -If #GNetworkMonitor:network-available is %TRUE, then the -connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there -is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if -the host has a default route, but appears to be unable to actually -reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the -host is trapped behind a "captive portal" that requires some sort -of login or acknowledgement before allowing full Internet access). - -Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and -%G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are -reachable but others are not. In this case, applications can -attempt to connect to remote servers, but should gracefully fall -back to their "offline" behavior if the connection attempt fails. - - - the network connectivity state - - - - - the #GNetworkMonitor - - - - - - Checks if the network is available. "Available" here means that the -system has a default route available for at least one of IPv4 or -IPv6. It does not necessarily imply that the public Internet is -reachable. See #GNetworkMonitor:network-available for more details. - - - whether the network is available - - - - - the #GNetworkMonitor - - - - - - Checks if the network is metered. -See #GNetworkMonitor:network-metered for more details. - - - whether the connection is metered - - - - - the #GNetworkMonitor - - - - - - More detailed information about the host's network connectivity. -See g_network_monitor_get_connectivity() and -#GNetworkConnectivity for more details. - - - - Whether the network is considered available. That is, whether the -system has a default route for at least one of IPv4 or IPv6. - -Real-world networks are of course much more complicated than -this; the machine may be connected to a wifi hotspot that -requires payment before allowing traffic through, or may be -connected to a functioning router that has lost its own upstream -connectivity. Some hosts might only be accessible when a VPN is -active. Other hosts might only be accessible when the VPN is -not active. Thus, it is best to use g_network_monitor_can_reach() -or g_network_monitor_can_reach_async() to test for reachability -on a host-by-host basis. (On the other hand, when the property is -%FALSE, the application can reasonably expect that no remote -hosts at all are reachable, and should indicate this to the user -in its UI.) - -See also #GNetworkMonitor::network-changed. - - - - Whether the network is considered metered. That is, whether the -system has traffic flowing through the default connection that is -subject to limitations set by service providers. For example, traffic -might be billed by the amount of data transmitted, or there might be a -quota on the amount of traffic per month. This is typical with tethered -connections (3G and 4G) and in such situations, bandwidth intensive -applications may wish to avoid network activity where possible if it will -cost the user money or use up their limited quota. - -If more information is required about specific devices then the -system network management API should be used instead (for example, -NetworkManager or ConnMan). - -If this information is not available then no networks will be -marked as metered. - -See also #GNetworkMonitor:network-available. - - - - Emitted when the network configuration changes. - - - - - - the current value of #GNetworkMonitor:network-available - - - - - - - The virtual function table for #GNetworkMonitor. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - %TRUE if @connectable is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GNetworkMonitor - - - - a #GSocketConnectable - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback to call when the - request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if network is reachable, %FALSE if not. - - - - - a #GNetworkMonitor - - - - a #GAsyncResult - - - - - - - - Like #GNetworkAddress does with hostnames, #GNetworkService -provides an easy way to resolve a SRV record, and then attempt to -connect to one of the hosts that implements that service, handling -service priority/weighting, multiple IP addresses, and multiple -address families. - -See #GSrvTarget for more information about SRV records, and see -#GSocketConnectable for an example of using the connectable -interface. - - - - Creates a new #GNetworkService representing the given @service, -@protocol, and @domain. This will initially be unresolved; use the -#GSocketConnectable interface to resolve it. - - - a new #GNetworkService - - - - - the service type to look up (eg, "ldap") - - - - the networking protocol to use for @service (eg, "tcp") - - - - the DNS domain to look up the service in - - - - - - Gets the domain that @srv serves. This might be either UTF-8 or -ASCII-encoded, depending on what @srv was created with. - - - @srv's domain name - - - - - a #GNetworkService - - - - - - Gets @srv's protocol name (eg, "tcp"). - - - @srv's protocol name - - - - - a #GNetworkService - - - - - - Get's the URI scheme used to resolve proxies. By default, the service name -is used as scheme. - - - @srv's scheme name - - - - - a #GNetworkService - - - - - - Gets @srv's service name (eg, "ldap"). - - - @srv's service name - - - - - a #GNetworkService - - - - - - Set's the URI scheme used to resolve proxies. By default, the service name -is used as scheme. - - - - - - - a #GNetworkService - - - - a URI scheme - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GNotification is a mechanism for creating a notification to be shown -to the user -- typically as a pop-up notification presented by the -desktop environment shell. - -The key difference between #GNotification and other similar APIs is -that, if supported by the desktop environment, notifications sent -with #GNotification will persist after the application has exited, -and even across system reboots. - -Since the user may click on a notification while the application is -not running, applications using #GNotification should be able to be -started as a D-Bus service, using #GApplication. - -User interaction with a notification (either the default action, or -buttons) must be associated with actions on the application (ie: -"app." actions). It is not possible to route user interaction -through the notification itself, because the object will not exist if -the application is autostarted as a result of a notification being -clicked. - -A notification can be sent with g_application_send_notification(). - - Creates a new #GNotification with @title as its title. - -After populating @notification with more details, it can be sent to -the desktop shell with g_application_send_notification(). Changing -any properties after this call will not have any effect until -resending @notification. - - - a new #GNotification instance - - - - - the title of the notification - - - - - - Adds a button to @notification that activates the action in -@detailed_action when clicked. That action must be an -application-wide action (starting with "app."). If @detailed_action -contains a target, the action will be activated with that target as -its parameter. - -See g_action_parse_detailed_name() for a description of the format -for @detailed_action. - - - - - - - a #GNotification - - - - label of the button - - - - a detailed action name - - - - - - Adds a button to @notification that activates @action when clicked. -@action must be an application-wide action (it must start with "app."). - -If @target_format is given, it is used to collect remaining -positional parameters into a #GVariant instance, similar to -g_variant_new(). @action will be activated with that #GVariant as its -parameter. - - - - - - - a #GNotification - - - - label of the button - - - - an action name - - - - a #GVariant format string, or %NULL - - - - positional parameters, as determined by @target_format - - - - - - Adds a button to @notification that activates @action when clicked. -@action must be an application-wide action (it must start with "app."). - -If @target is non-%NULL, @action will be activated with @target as -its parameter. - - - - - - - a #GNotification - - - - label of the button - - - - an action name - - - - a #GVariant to use as @action's parameter, or %NULL - - - - - - Sets the body of @notification to @body. - - - - - - - a #GNotification - - - - the new body for @notification, or %NULL - - - - - - Sets the default action of @notification to @detailed_action. This -action is activated when the notification is clicked on. - -The action in @detailed_action must be an application-wide action (it -must start with "app."). If @detailed_action contains a target, the -given action will be activated with that target as its parameter. -See g_action_parse_detailed_name() for a description of the format -for @detailed_action. - -When no default action is set, the application that the notification -was sent on is activated. - - - - - - - a #GNotification - - - - a detailed action name - - - - - - Sets the default action of @notification to @action. This action is -activated when the notification is clicked on. It must be an -application-wide action (it must start with "app."). - -If @target_format is given, it is used to collect remaining -positional parameters into a #GVariant instance, similar to -g_variant_new(). @action will be activated with that #GVariant as its -parameter. - -When no default action is set, the application that the notification -was sent on is activated. - - - - - - - a #GNotification - - - - an action name - - - - a #GVariant format string, or %NULL - - - - positional parameters, as determined by @target_format - - - - - - Sets the default action of @notification to @action. This action is -activated when the notification is clicked on. It must be an -application-wide action (start with "app."). - -If @target is non-%NULL, @action will be activated with @target as -its parameter. - -When no default action is set, the application that the notification -was sent on is activated. - - - - - - - a #GNotification - - - - an action name - - - - a #GVariant to use as @action's parameter, or %NULL - - - - - - Sets the icon of @notification to @icon. - - - - - - - a #GNotification - - - - the icon to be shown in @notification, as a #GIcon - - - - - - Sets the priority of @notification to @priority. See -#GNotificationPriority for possible values. - - - - - - - a #GNotification - - - - a #GNotificationPriority - - - - - - Sets the title of @notification to @title. - - - - - - - a #GNotification - - - - the new title for @notification - - - - - - Deprecated in favor of g_notification_set_priority(). - Since 2.42, this has been deprecated in favour of - g_notification_set_priority(). - - - - - - - a #GNotification - - - - %TRUE if @notification is urgent - - - - - - - Priority levels for #GNotifications. - - the default priority, to be used for the - majority of notifications (for example email messages, software updates, - completed download/sync operations) - - - for notifications that do not require - immediate attention - typically used for contextual background - information, such as contact birthdays or local weather - - - for events that require more attention, - usually because responses are time-sensitive (for example chat and SMS - messages or alarms) - - - for urgent notifications, or notifications - that require a response in a short space of time (for example phone calls - or emergency warnings) - - - - - - - - - - - - - - - - - - - - - - - - - Structure used for scatter/gather data output when sending multiple -messages or packets in one go. You generally pass in an array of -#GOutputVectors and the operation will use all the buffers as if they -were one buffer. - -If @address is %NULL then the message is sent to the default receiver -(as previously set by g_socket_connect()). - - - a #GSocketAddress, or %NULL - - - - pointer to an array of output vectors - - - - the number of output vectors pointed to by @vectors. - - - - initialize to 0. Will be set to the number of bytes - that have been sent - - - - a pointer - to an array of #GSocketControlMessages, or %NULL. - - - - - - number of elements in @control_messages. - - - - - #GOutputStream has functions to write to a stream (g_output_stream_write()), -to close a stream (g_output_stream_close()) and to flush pending writes -(g_output_stream_flush()). - -To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). - -See the documentation for #GIOStream for details of thread safety of -streaming APIs. - -All of these functions have async variants too. - - - Requests an asynchronous close of the stream, releasing resources -related to it. When the operation is finished @callback will be -called. You can then call g_output_stream_close_finish() to get -the result of the operation. - -For behaviour details see g_output_stream_close(). - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - - - - - - - A #GOutputStream. - - - - the io priority of the request. - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Closes an output stream. - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - - - - - Forces a write of all user-space buffered data for the given -@stream. Will block during the operation. Closing the stream will -implicitly cause a flush. - -This function is optional for inherited classes. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on success, %FALSE on error - - - - - a #GOutputStream. - - - - optional cancellable object - - - - - - Forces an asynchronous write of all user-space buffered data for -the given @stream. -For behaviour details see g_output_stream_flush(). - -When the operation is finished @callback will be -called. You can then call g_output_stream_flush_finish() to get the -result of the operation. - - - - - - - a #GOutputStream. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes flushing an output stream. - - - %TRUE if flush operation succeeded, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a GAsyncResult. - - - - - - Splices an input stream into an output stream. - - - a #gssize containing the size of the data spliced, or - -1 if an error occurred. Note that if the number of bytes - spliced is greater than %G_MAXSSIZE, then that will be - returned, and there is no way to determine the actual number - of bytes spliced. - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Splices a stream asynchronously. -When the operation is finished @callback will be called. -You can then call g_output_stream_splice_finish() to get the -result of the operation. - -For the synchronous, blocking version of this function, see -g_output_stream_splice(). - - - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - - - Finishes an asynchronous stream splice operation. - - - a #gssize of the number of bytes spliced. Note that if the - number of bytes spliced is greater than %G_MAXSSIZE, then that - will be returned, and there is no way to determine the actual - number of bytes spliced. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - Request an asynchronous write of @count bytes from @buffer into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_write_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a -%G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes written will be passed to the -@callback. It is not an error if this is not the same as the -requested size, as it can happen e.g. on a partial I/O error, -but generally we try to write as many bytes as requested. - -You are guaranteed that this method will never fail with -%G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the -method will just wait until this changes. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - -For the synchronous, blocking version of this function, see -g_output_stream_write(). - -Note that no copy of @buffer will be made, so it must stay valid -until @callback is called. See g_output_stream_write_bytes_async() -for a #GBytes version that will automatically hold a reference to -the contents (without copying) for the duration of the call. - - - - - - - A #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream write operation. - - - a #gssize containing the number of bytes written to the stream. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - Tries to write @count bytes from @buffer into the stream. Will block -during the operation. - -If count is 0, returns 0 and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes written to the stream is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. on a partial I/O error, or if there is not enough -storage in the stream. All writes block until at least one byte -is written or an error occurs; 0 is never returned (unless -@count is 0). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - - - Number of bytes written, or -1 on error - - - - - a #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - optional cancellable object - - - - - - Request an asynchronous write of the bytes contained in @n_vectors @vectors into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_writev_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -On success, the number of bytes written will be passed to the -@callback. It is not an error if this is not the same as the -requested size, as it can happen e.g. on a partial I/O error, -but generally we try to write as many bytes as requested. - -You are guaranteed that this method will never fail with -%G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the -method will just wait until this changes. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - -For the synchronous, blocking version of this function, see -g_output_stream_writev(). - -Note that no copy of @vectors will be made, so it must stay valid -until @callback is called. - - - - - - - A #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - the I/O priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream writev operation. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - location to store the number of bytes that were written to the stream - - - - - - Tries to write the bytes contained in the @n_vectors @vectors into the -stream. Will block during the operation. - -If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and -does nothing. - -On success, the number of bytes written to the stream is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. on a partial I/O error, or if there is not enough -storage in the stream. All writes block until at least one byte -is written or an error occurs; 0 is never returned (unless -@n_vectors is 0 or the sum of all bytes in @vectors is 0). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -Some implementations of g_output_stream_writev() may have limitations on the -aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these -are exceeded. For example, when writing to a local file on UNIX platforms, -the aggregate buffer size must not exceed %G_MAXSSIZE bytes. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - optional cancellable object - - - - - - Clears the pending flag on @stream. - - - - - - - output stream - - - - - - Closes the stream, releasing resources related to it. - -Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. -Closing a stream multiple times will not return an error. - -Closing a stream will automatically flush any outstanding buffers in the -stream. - -Streams will be automatically closed when the last reference -is dropped, but you might want to call this function to make sure -resources are released as early as possible. - -Some streams might keep the backing store of the stream (e.g. a file descriptor) -open after the stream is closed. See the documentation for the individual -stream for details. - -On failure the first error that happened will be reported, but the close -operation will finish as much as possible. A stream that failed to -close will still return %G_IO_ERROR_CLOSED for all operations. Still, it -is important to check and report the error to the user, otherwise -there might be a loss of data as all data might not be written. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. -Cancelling a close will still leave the stream closed, but there some streams -can use a faster close that doesn't block to e.g. check errors. On -cancellation (as with any error) there is no guarantee that all written -data will reach the target. - - - %TRUE on success, %FALSE on failure - - - - - A #GOutputStream. - - - - optional cancellable object - - - - - - Requests an asynchronous close of the stream, releasing resources -related to it. When the operation is finished @callback will be -called. You can then call g_output_stream_close_finish() to get -the result of the operation. - -For behaviour details see g_output_stream_close(). - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - - - - - - - A #GOutputStream. - - - - the io priority of the request. - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Closes an output stream. - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - Forces a write of all user-space buffered data for the given -@stream. Will block during the operation. Closing the stream will -implicitly cause a flush. - -This function is optional for inherited classes. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE on success, %FALSE on error - - - - - a #GOutputStream. - - - - optional cancellable object - - - - - - Forces an asynchronous write of all user-space buffered data for -the given @stream. -For behaviour details see g_output_stream_flush(). - -When the operation is finished @callback will be -called. You can then call g_output_stream_flush_finish() to get the -result of the operation. - - - - - - - a #GOutputStream. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes flushing an output stream. - - - %TRUE if flush operation succeeded, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a GAsyncResult. - - - - - - Checks if an output stream has pending actions. - - - %TRUE if @stream has pending actions. - - - - - a #GOutputStream. - - - - - - Checks if an output stream has already been closed. - - - %TRUE if @stream is closed. %FALSE otherwise. - - - - - a #GOutputStream. - - - - - - Checks if an output stream is being closed. This can be -used inside e.g. a flush implementation to see if the -flush (or other i/o operation) is called from within -the closing operation. - - - %TRUE if @stream is being closed. %FALSE otherwise. - - - - - a #GOutputStream. - - - - - - This is a utility function around g_output_stream_write_all(). It -uses g_strdup_vprintf() to turn @format and @... into a string that -is then written to @stream. - -See the documentation of g_output_stream_write_all() about the -behavior of the actual write operation. - -Note that partial writes cannot be properly checked with this -function due to the variable length of the written string, if you -need precise control over partial write failures, you need to -create you own printf()-like wrapper around g_output_stream_write() -or g_output_stream_write_all(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - location to store the number of bytes that was - written to the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - location to store the error occurring, or %NULL to ignore - - - - the format string. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Sets @stream to have actions pending. If the pending flag is -already set or @stream is closed, it will return %FALSE and set -@error. - - - %TRUE if pending was previously unset and is now set. - - - - - a #GOutputStream. - - - - - - Splices an input stream into an output stream. - - - a #gssize containing the size of the data spliced, or - -1 if an error occurred. Note that if the number of bytes - spliced is greater than %G_MAXSSIZE, then that will be - returned, and there is no way to determine the actual number - of bytes spliced. - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Splices a stream asynchronously. -When the operation is finished @callback will be called. -You can then call g_output_stream_splice_finish() to get the -result of the operation. - -For the synchronous, blocking version of this function, see -g_output_stream_splice(). - - - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - - - Finishes an asynchronous stream splice operation. - - - a #gssize of the number of bytes spliced. Note that if the - number of bytes spliced is greater than %G_MAXSSIZE, then that - will be returned, and there is no way to determine the actual - number of bytes spliced. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - This is a utility function around g_output_stream_write_all(). It -uses g_strdup_vprintf() to turn @format and @args into a string that -is then written to @stream. - -See the documentation of g_output_stream_write_all() about the -behavior of the actual write operation. - -Note that partial writes cannot be properly checked with this -function due to the variable length of the written string, if you -need precise control over partial write failures, you need to -create you own printf()-like wrapper around g_output_stream_write() -or g_output_stream_write_all(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - location to store the number of bytes that was - written to the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - location to store the error occurring, or %NULL to ignore - - - - the format string. See the printf() documentation - - - - the parameters to insert into the format string - - - - - - Tries to write @count bytes from @buffer into the stream. Will block -during the operation. - -If count is 0, returns 0 and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes written to the stream is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. on a partial I/O error, or if there is not enough -storage in the stream. All writes block until at least one byte -is written or an error occurs; 0 is never returned (unless -@count is 0). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -On error -1 is returned and @error is set accordingly. - - - Number of bytes written, or -1 on error - - - - - a #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - optional cancellable object - - - - - - Tries to write @count bytes from @buffer into the stream. Will block -during the operation. - -This function is similar to g_output_stream_write(), except it tries to -write as many bytes as requested, only stopping on an error. - -On a successful write of @count bytes, %TRUE is returned, and @bytes_written -is set to @count. - -If there is an error during the operation %FALSE is returned and @error -is set to indicate the error status. - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_written will be set to the number of bytes that were -successfully written before the error was encountered. This -functionality is only available from C. If you need it from another -language then you must write your own loop around -g_output_stream_write(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - location to store the number of bytes that was - written to the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous write of @count bytes from @buffer into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_write_all_finish() to get the result of the -operation. - -This is the asynchronous version of g_output_stream_write_all(). - -Call g_output_stream_write_all_finish() to collect the result. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -Note that no copy of @buffer will be made, so it must stay valid -until @callback is called. - - - - - - - A #GOutputStream - - - - the buffer containing the data to write - - - - - - the number of bytes to write - - - - the io priority of the request - - - - optional #GCancellable object, %NULL to ignore - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous stream write operation started with -g_output_stream_write_all_async(). - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_written will be set to the number of bytes that were -successfully written before the error was encountered. This -functionality is only available from C. If you need it from another -language then you must write your own loop around -g_output_stream_write_async(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream - - - - a #GAsyncResult - - - - location to store the number of bytes that was written to the stream - - - - - - Request an asynchronous write of @count bytes from @buffer into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_write_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -A value of @count larger than %G_MAXSSIZE will cause a -%G_IO_ERROR_INVALID_ARGUMENT error. - -On success, the number of bytes written will be passed to the -@callback. It is not an error if this is not the same as the -requested size, as it can happen e.g. on a partial I/O error, -but generally we try to write as many bytes as requested. - -You are guaranteed that this method will never fail with -%G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the -method will just wait until this changes. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - -For the synchronous, blocking version of this function, see -g_output_stream_write(). - -Note that no copy of @buffer will be made, so it must stay valid -until @callback is called. See g_output_stream_write_bytes_async() -for a #GBytes version that will automatically hold a reference to -the contents (without copying) for the duration of the call. - - - - - - - A #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - A wrapper function for g_output_stream_write() which takes a -#GBytes as input. This can be more convenient for use by language -bindings or in other cases where the refcounted nature of #GBytes -is helpful over a bare pointer interface. - -However, note that this function may still perform partial writes, -just like g_output_stream_write(). If that occurs, to continue -writing, you will need to create a new #GBytes containing just the -remaining bytes, using g_bytes_new_from_bytes(). Passing the same -#GBytes instance multiple times potentially can result in duplicated -data in the output stream. - - - Number of bytes written, or -1 on error - - - - - a #GOutputStream. - - - - the #GBytes to write - - - - optional cancellable object - - - - - - This function is similar to g_output_stream_write_async(), but -takes a #GBytes as input. Due to the refcounted nature of #GBytes, -this allows the stream to avoid taking a copy of the data. - -However, note that this function may still perform partial writes, -just like g_output_stream_write_async(). If that occurs, to continue -writing, you will need to create a new #GBytes containing just the -remaining bytes, using g_bytes_new_from_bytes(). Passing the same -#GBytes instance multiple times potentially can result in duplicated -data in the output stream. - -For the synchronous, blocking version of this function, see -g_output_stream_write_bytes(). - - - - - - - A #GOutputStream. - - - - The bytes to write - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream write-from-#GBytes operation. - - - a #gssize containing the number of bytes written to the stream. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - Finishes a stream write operation. - - - a #gssize containing the number of bytes written to the stream. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - Tries to write the bytes contained in the @n_vectors @vectors into the -stream. Will block during the operation. - -If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and -does nothing. - -On success, the number of bytes written to the stream is returned. -It is not an error if this is not the same as the requested size, as it -can happen e.g. on a partial I/O error, or if there is not enough -storage in the stream. All writes block until at least one byte -is written or an error occurs; 0 is never returned (unless -@n_vectors is 0 or the sum of all bytes in @vectors is 0). - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - -Some implementations of g_output_stream_writev() may have limitations on the -aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these -are exceeded. For example, when writing to a local file on UNIX platforms, -the aggregate buffer size must not exceed %G_MAXSSIZE bytes. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - optional cancellable object - - - - - - Tries to write the bytes contained in the @n_vectors @vectors into the -stream. Will block during the operation. - -This function is similar to g_output_stream_writev(), except it tries to -write as many bytes as requested, only stopping on an error. - -On a successful write of all @n_vectors vectors, %TRUE is returned, and -@bytes_written is set to the sum of all the sizes of @vectors. - -If there is an error during the operation %FALSE is returned and @error -is set to indicate the error status. - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_written will be set to the number of bytes that were -successfully written before the error was encountered. This -functionality is only available from C. If you need it from another -language then you must write your own loop around -g_output_stream_write(). - -The content of the individual elements of @vectors might be changed by this -function. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Request an asynchronous write of the bytes contained in the @n_vectors @vectors into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_writev_all_finish() to get the result of the -operation. - -This is the asynchronous version of g_output_stream_writev_all(). - -Call g_output_stream_writev_all_finish() to collect the result. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -Note that no copy of @vectors will be made, so it must stay valid -until @callback is called. The content of the individual elements -of @vectors might be changed by this function. - - - - - - - A #GOutputStream - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - the I/O priority of the request - - - - optional #GCancellable object, %NULL to ignore - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous stream write operation started with -g_output_stream_writev_all_async(). - -As a special exception to the normal conventions for functions that -use #GError, if this function returns %FALSE (and sets @error) then -@bytes_written will be set to the number of bytes that were -successfully written before the error was encountered. This -functionality is only available from C. If you need it from another -language then you must write your own loop around -g_output_stream_writev_async(). - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream - - - - a #GAsyncResult - - - - location to store the number of bytes that were written to the stream - - - - - - Request an asynchronous write of the bytes contained in @n_vectors @vectors into -the stream. When the operation is finished @callback will be called. -You can then call g_output_stream_writev_finish() to get the result of the -operation. - -During an async request no other sync and async calls are allowed, -and will result in %G_IO_ERROR_PENDING errors. - -On success, the number of bytes written will be passed to the -@callback. It is not an error if this is not the same as the -requested size, as it can happen e.g. on a partial I/O error, -but generally we try to write as many bytes as requested. - -You are guaranteed that this method will never fail with -%G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the -method will just wait until this changes. - -Any outstanding I/O request with higher priority (lower numerical -value) will be executed before an outstanding request with lower -priority. Default priority is %G_PRIORITY_DEFAULT. - -The asynchronous methods have a default fallback that uses threads -to implement asynchronicity, so they are optional for inheriting -classes. However, if you override one you must override all. - -For the synchronous, blocking version of this function, see -g_output_stream_writev(). - -Note that no copy of @vectors will be made, so it must stay valid -until @callback is called. - - - - - - - A #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - the I/O priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes a stream writev operation. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - location to store the number of bytes that were written to the stream - - - - - - - - - - - - - - - - - - - - - Number of bytes written, or -1 on error - - - - - a #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - optional cancellable object - - - - - - - - - - a #gssize containing the size of the data spliced, or - -1 if an error occurred. Note that if the number of bytes - spliced is greater than %G_MAXSSIZE, then that will be - returned, and there is no way to determine the actual number - of bytes spliced. - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - %TRUE on success, %FALSE on error - - - - - a #GOutputStream. - - - - optional cancellable object - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GOutputStream. - - - - the buffer containing the data to write. - - - - - - the number of bytes to write - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #gssize containing the number of bytes written to the stream. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GOutputStream. - - - - a #GInputStream. - - - - a set of #GOutputStreamSpliceFlags. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - - - - - - - a #gssize of the number of bytes spliced. Note that if the - number of bytes spliced is greater than %G_MAXSSIZE, then that - will be returned, and there is no way to determine the actual - number of bytes spliced. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - - - - - a #GOutputStream. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if flush operation succeeded, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a GAsyncResult. - - - - - - - - - - - - - - A #GOutputStream. - - - - the io priority of the request. - - - - optional cancellable object - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE if stream was successfully closed, %FALSE otherwise. - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - - - - - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - optional cancellable object - - - - - - - - - - - - - - A #GOutputStream. - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - the I/O priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - callback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - - - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - a #GAsyncResult. - - - - location to store the number of bytes that were written to the stream - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GOutputStreamSpliceFlags determine how streams should be spliced. - - Do not close either stream. - - - Close the source stream after - the splice. - - - Close the target stream after - the splice. - - - - Structure used for scatter/gather data output. -You generally pass in an array of #GOutputVectors -and the operation will use all the buffers as if they were -one buffer. - - - Pointer to a buffer of data to read. - - - - the size of @buffer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for proxy functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - - - - - - - - Extension point for proxy resolving functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - #GPasswordSave is used to indicate the lifespan of a saved password. - -#Gvfs stores passwords in the Gnome keyring when this flag allows it -to, and later retrieves it again from there. - - never save a password. - - - save a password for the session. - - - save a password permanently. - - - - A #GPermission represents the status of the caller's permission to -perform a certain action. - -You can query if the action is currently allowed and if it is -possible to acquire the permission so that the action will be allowed -in the future. - -There is also an API to actually acquire the permission and one to -release it. - -As an example, a #GPermission might represent the ability for the -user to write to a #GSettings object. This #GPermission object could -then be used to decide if it is appropriate to show a "Click here to -unlock" button in a dialog and to provide the mechanism to invoke -when that button is clicked. - - - Attempts to acquire the permission represented by @permission. - -The precise method by which this happens depends on the permission -and the underlying authentication mechanism. A simple example is -that a dialog may appear asking the user to enter their password. - -You should check with g_permission_get_can_acquire() before calling -this function. - -If the permission is acquired then %TRUE is returned. Otherwise, -%FALSE is returned and @error is set appropriately. - -This call is blocking, likely for a very long time (in the case that -user interaction is required). See g_permission_acquire_async() for -the non-blocking version. - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - Attempts to acquire the permission represented by @permission. - -This is the first half of the asynchronous version of -g_permission_acquire(). - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - Collects the result of attempting to acquire the permission -represented by @permission. - -This is the second half of the asynchronous version of -g_permission_acquire(). - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - Attempts to release the permission represented by @permission. - -The precise method by which this happens depends on the permission -and the underlying authentication mechanism. In most cases the -permission will be dropped immediately without further action. - -You should check with g_permission_get_can_release() before calling -this function. - -If the permission is released then %TRUE is returned. Otherwise, -%FALSE is returned and @error is set appropriately. - -This call is blocking, likely for a very long time (in the case that -user interaction is required). See g_permission_release_async() for -the non-blocking version. - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - Attempts to release the permission represented by @permission. - -This is the first half of the asynchronous version of -g_permission_release(). - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - Collects the result of attempting to release the permission -represented by @permission. - -This is the second half of the asynchronous version of -g_permission_release(). - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - Attempts to acquire the permission represented by @permission. - -The precise method by which this happens depends on the permission -and the underlying authentication mechanism. A simple example is -that a dialog may appear asking the user to enter their password. - -You should check with g_permission_get_can_acquire() before calling -this function. - -If the permission is acquired then %TRUE is returned. Otherwise, -%FALSE is returned and @error is set appropriately. - -This call is blocking, likely for a very long time (in the case that -user interaction is required). See g_permission_acquire_async() for -the non-blocking version. - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - Attempts to acquire the permission represented by @permission. - -This is the first half of the asynchronous version of -g_permission_acquire(). - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - Collects the result of attempting to acquire the permission -represented by @permission. - -This is the second half of the asynchronous version of -g_permission_acquire(). - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - Gets the value of the 'allowed' property. This property is %TRUE if -the caller currently has permission to perform the action that -@permission represents the permission to perform. - - - the value of the 'allowed' property - - - - - a #GPermission instance - - - - - - Gets the value of the 'can-acquire' property. This property is %TRUE -if it is generally possible to acquire the permission by calling -g_permission_acquire(). - - - the value of the 'can-acquire' property - - - - - a #GPermission instance - - - - - - Gets the value of the 'can-release' property. This property is %TRUE -if it is generally possible to release the permission by calling -g_permission_release(). - - - the value of the 'can-release' property - - - - - a #GPermission instance - - - - - - This function is called by the #GPermission implementation to update -the properties of the permission. You should never call this -function except from a #GPermission implementation. - -GObject notify signals are generated, as appropriate. - - - - - - - a #GPermission instance - - - - the new value for the 'allowed' property - - - - the new value for the 'can-acquire' property - - - - the new value for the 'can-release' property - - - - - - Attempts to release the permission represented by @permission. - -The precise method by which this happens depends on the permission -and the underlying authentication mechanism. In most cases the -permission will be dropped immediately without further action. - -You should check with g_permission_get_can_release() before calling -this function. - -If the permission is released then %TRUE is returned. Otherwise, -%FALSE is returned and @error is set appropriately. - -This call is blocking, likely for a very long time (in the case that -user interaction is required). See g_permission_release_async() for -the non-blocking version. - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - Attempts to release the permission represented by @permission. - -This is the first half of the asynchronous version of -g_permission_release(). - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - Collects the result of attempting to release the permission -represented by @permission. - -This is the second half of the asynchronous version of -g_permission_release(). - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - %TRUE if the caller currently has permission to perform the action that -@permission represents the permission to perform. - - - - %TRUE if it is generally possible to acquire the permission by calling -g_permission_acquire(). - - - - %TRUE if it is generally possible to release the permission by calling -g_permission_release(). - - - - - - - - - - - - - - - - - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - - - - - %TRUE if the permission was successfully acquired - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - - - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GPermission instance - - - - a #GCancellable, or %NULL - - - - the #GAsyncReadyCallback to call when done - - - - the user data to pass to @callback - - - - - - - - - - %TRUE if the permission was successfully released - - - - - a #GPermission instance - - - - the #GAsyncResult given to the #GAsyncReadyCallback - - - - - - - - - - - - - - - - #GPollableInputStream is implemented by #GInputStreams that -can be polled for readiness to read. This can be used when -interfacing with a non-GIO API that expects -UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. - - - - Checks if @stream is actually pollable. Some classes may implement -#GPollableInputStream but have only certain instances of that class -be pollable. If this method returns %FALSE, then the behavior of -other #GPollableInputStream methods is undefined. - -For any given stream, the value returned by this method is constant; -a stream cannot switch from pollable to non-pollable or vice versa. - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableInputStream. - - - - - - Creates a #GSource that triggers when @stream can be read, or -@cancellable is triggered or an error occurs. The callback on the -source is of the #GPollableSourceFunc type. - -As with g_pollable_input_stream_is_readable(), it is possible that -the stream may not actually be readable even after the source -triggers, so you should use g_pollable_input_stream_read_nonblocking() -rather than g_input_stream_read() from the callback. - - - a new #GSource - - - - - a #GPollableInputStream. - - - - a #GCancellable, or %NULL - - - - - - Checks if @stream can be read. - -Note that some stream types may not be able to implement this 100% -reliably, and it is possible that a call to g_input_stream_read() -after this returns %TRUE would still block. To guarantee -non-blocking behavior, you should always use -g_pollable_input_stream_read_nonblocking(), which will return a -%G_IO_ERROR_WOULD_BLOCK error rather than blocking. - - - %TRUE if @stream is readable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_input_stream_is_readable() returning %TRUE, and the - next attempt to read will return the error. - - - - - a #GPollableInputStream. - - - - - - Attempts to read up to @count bytes from @stream into @buffer, as -with g_input_stream_read(). If @stream is not currently readable, -this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can -use g_pollable_input_stream_create_source() to create a #GSource -that will be triggered when @stream is readable. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - - - the number of bytes read, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableInputStream - - - - a buffer to - read data into (which should be at least @count bytes long). - - - - - - the number of bytes you want to read - - - - - - Checks if @stream is actually pollable. Some classes may implement -#GPollableInputStream but have only certain instances of that class -be pollable. If this method returns %FALSE, then the behavior of -other #GPollableInputStream methods is undefined. - -For any given stream, the value returned by this method is constant; -a stream cannot switch from pollable to non-pollable or vice versa. - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableInputStream. - - - - - - Creates a #GSource that triggers when @stream can be read, or -@cancellable is triggered or an error occurs. The callback on the -source is of the #GPollableSourceFunc type. - -As with g_pollable_input_stream_is_readable(), it is possible that -the stream may not actually be readable even after the source -triggers, so you should use g_pollable_input_stream_read_nonblocking() -rather than g_input_stream_read() from the callback. - - - a new #GSource - - - - - a #GPollableInputStream. - - - - a #GCancellable, or %NULL - - - - - - Checks if @stream can be read. - -Note that some stream types may not be able to implement this 100% -reliably, and it is possible that a call to g_input_stream_read() -after this returns %TRUE would still block. To guarantee -non-blocking behavior, you should always use -g_pollable_input_stream_read_nonblocking(), which will return a -%G_IO_ERROR_WOULD_BLOCK error rather than blocking. - - - %TRUE if @stream is readable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_input_stream_is_readable() returning %TRUE, and the - next attempt to read will return the error. - - - - - a #GPollableInputStream. - - - - - - Attempts to read up to @count bytes from @stream into @buffer, as -with g_input_stream_read(). If @stream is not currently readable, -this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can -use g_pollable_input_stream_create_source() to create a #GSource -that will be triggered when @stream is readable. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - - - the number of bytes read, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableInputStream - - - - a buffer to - read data into (which should be at least @count bytes long). - - - - - - the number of bytes you want to read - - - - a #GCancellable, or %NULL - - - - - - - The interface for pollable input streams. - -The default implementation of @can_poll always returns %TRUE. - -The default implementation of @read_nonblocking calls -g_pollable_input_stream_is_readable(), and then calls -g_input_stream_read() if it returns %TRUE. This means you only need -to override it if it is possible that your @is_readable -implementation may return %TRUE when the stream is not actually -readable. - - - The parent interface. - - - - - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableInputStream. - - - - - - - - - - %TRUE if @stream is readable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_input_stream_is_readable() returning %TRUE, and the - next attempt to read will return the error. - - - - - a #GPollableInputStream. - - - - - - - - - - a new #GSource - - - - - a #GPollableInputStream. - - - - a #GCancellable, or %NULL - - - - - - - - - - the number of bytes read, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableInputStream - - - - a buffer to - read data into (which should be at least @count bytes long). - - - - - - the number of bytes you want to read - - - - - - - - #GPollableOutputStream is implemented by #GOutputStreams that -can be polled for readiness to write. This can be used when -interfacing with a non-GIO API that expects -UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. - - - - Checks if @stream is actually pollable. Some classes may implement -#GPollableOutputStream but have only certain instances of that -class be pollable. If this method returns %FALSE, then the behavior -of other #GPollableOutputStream methods is undefined. - -For any given stream, the value returned by this method is constant; -a stream cannot switch from pollable to non-pollable or vice versa. - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableOutputStream. - - - - - - Creates a #GSource that triggers when @stream can be written, or -@cancellable is triggered or an error occurs. The callback on the -source is of the #GPollableSourceFunc type. - -As with g_pollable_output_stream_is_writable(), it is possible that -the stream may not actually be writable even after the source -triggers, so you should use g_pollable_output_stream_write_nonblocking() -rather than g_output_stream_write() from the callback. - - - a new #GSource - - - - - a #GPollableOutputStream. - - - - a #GCancellable, or %NULL - - - - - - Checks if @stream can be written. - -Note that some stream types may not be able to implement this 100% -reliably, and it is possible that a call to g_output_stream_write() -after this returns %TRUE would still block. To guarantee -non-blocking behavior, you should always use -g_pollable_output_stream_write_nonblocking(), which will return a -%G_IO_ERROR_WOULD_BLOCK error rather than blocking. - - - %TRUE if @stream is writable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_output_stream_is_writable() returning %TRUE, and the - next attempt to write will return the error. - - - - - a #GPollableOutputStream. - - - - - - Attempts to write up to @count bytes from @buffer to @stream, as -with g_output_stream_write(). If @stream is not currently writable, -this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can -use g_pollable_output_stream_create_source() to create a #GSource -that will be triggered when @stream is writable. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - -Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying -transports like D/TLS require that you re-send the same @buffer and -@count in the next write call. - - - the number of bytes written, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableOutputStream - - - - a buffer to write - data from - - - - - - the number of bytes you want to write - - - - - - Attempts to write the bytes contained in the @n_vectors @vectors to @stream, -as with g_output_stream_writev(). If @stream is not currently writable, -this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can -use g_pollable_output_stream_create_source() to create a #GSource -that will be triggered when @stream is writable. @error will *not* be -set in that case. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - -Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying -transports like D/TLS require that you re-send the same @vectors and -@n_vectors in the next write call. - - - %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK -if the stream is not currently writable (and @error is *not* set), or -%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will -be set. - - - - - a #GPollableOutputStream - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - - - Checks if @stream is actually pollable. Some classes may implement -#GPollableOutputStream but have only certain instances of that -class be pollable. If this method returns %FALSE, then the behavior -of other #GPollableOutputStream methods is undefined. - -For any given stream, the value returned by this method is constant; -a stream cannot switch from pollable to non-pollable or vice versa. - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableOutputStream. - - - - - - Creates a #GSource that triggers when @stream can be written, or -@cancellable is triggered or an error occurs. The callback on the -source is of the #GPollableSourceFunc type. - -As with g_pollable_output_stream_is_writable(), it is possible that -the stream may not actually be writable even after the source -triggers, so you should use g_pollable_output_stream_write_nonblocking() -rather than g_output_stream_write() from the callback. - - - a new #GSource - - - - - a #GPollableOutputStream. - - - - a #GCancellable, or %NULL - - - - - - Checks if @stream can be written. - -Note that some stream types may not be able to implement this 100% -reliably, and it is possible that a call to g_output_stream_write() -after this returns %TRUE would still block. To guarantee -non-blocking behavior, you should always use -g_pollable_output_stream_write_nonblocking(), which will return a -%G_IO_ERROR_WOULD_BLOCK error rather than blocking. - - - %TRUE if @stream is writable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_output_stream_is_writable() returning %TRUE, and the - next attempt to write will return the error. - - - - - a #GPollableOutputStream. - - - - - - Attempts to write up to @count bytes from @buffer to @stream, as -with g_output_stream_write(). If @stream is not currently writable, -this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can -use g_pollable_output_stream_create_source() to create a #GSource -that will be triggered when @stream is writable. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - -Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying -transports like D/TLS require that you re-send the same @buffer and -@count in the next write call. - - - the number of bytes written, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableOutputStream - - - - a buffer to write - data from - - - - - - the number of bytes you want to write - - - - a #GCancellable, or %NULL - - - - - - Attempts to write the bytes contained in the @n_vectors @vectors to @stream, -as with g_output_stream_writev(). If @stream is not currently writable, -this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can -use g_pollable_output_stream_create_source() to create a #GSource -that will be triggered when @stream is writable. @error will *not* be -set in that case. - -Note that since this method never blocks, you cannot actually -use @cancellable to cancel it. However, it will return an error -if @cancellable has already been cancelled when you call, which -may happen if you call this method after a source triggers due -to having been cancelled. - -Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying -transports like D/TLS require that you re-send the same @vectors and -@n_vectors in the next write call. - - - %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK -if the stream is not currently writable (and @error is *not* set), or -%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will -be set. - - - - - a #GPollableOutputStream - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - a #GCancellable, or %NULL - - - - - - - The interface for pollable output streams. - -The default implementation of @can_poll always returns %TRUE. - -The default implementation of @write_nonblocking calls -g_pollable_output_stream_is_writable(), and then calls -g_output_stream_write() if it returns %TRUE. This means you only -need to override it if it is possible that your @is_writable -implementation may return %TRUE when the stream is not actually -writable. - -The default implementation of @writev_nonblocking calls -g_pollable_output_stream_write_nonblocking() for each vector, and converts -its return value and error (if set) to a #GPollableReturn. You should -override this where possible to avoid having to allocate a #GError to return -%G_IO_ERROR_WOULD_BLOCK. - - - The parent interface. - - - - - - - %TRUE if @stream is pollable, %FALSE if not. - - - - - a #GPollableOutputStream. - - - - - - - - - - %TRUE if @stream is writable, %FALSE if not. If an error - has occurred on @stream, this will result in - g_pollable_output_stream_is_writable() returning %TRUE, and the - next attempt to write will return the error. - - - - - a #GPollableOutputStream. - - - - - - - - - - a new #GSource - - - - - a #GPollableOutputStream. - - - - a #GCancellable, or %NULL - - - - - - - - - - the number of bytes written, or -1 on error (including - %G_IO_ERROR_WOULD_BLOCK). - - - - - a #GPollableOutputStream - - - - a buffer to write - data from - - - - - - the number of bytes you want to write - - - - - - - - - - %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK -if the stream is not currently writable (and @error is *not* set), or -%G_POLLABLE_RETURN_FAILED if there was an error in which case @error will -be set. - - - - - a #GPollableOutputStream - - - - the buffer containing the #GOutputVectors to write. - - - - - - the number of vectors to write - - - - location to store the number of bytes that were - written to the stream - - - - - - - - Return value for various IO operations that signal errors via the -return value and not necessarily via a #GError. - -This enum exists to be able to return errors to callers without having to -allocate a #GError. Allocating #GErrors can be quite expensive for -regularly happening errors like %G_IO_ERROR_WOULD_BLOCK. - -In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the -operation to give details about the error that happened. - - Generic error condition for when an operation fails. - - - The operation was successfully finished. - - - The operation would block. - - - - This is the function type of the callback used for the #GSource -returned by g_pollable_input_stream_create_source() and -g_pollable_output_stream_create_source(). - - - it should return %FALSE if the source should be removed. - - - - - the #GPollableInputStream or #GPollableOutputStream - - - - data passed in by the user. - - - - - - A #GPropertyAction is a way to get a #GAction with a state value -reflecting and controlling the value of a #GObject property. - -The state of the action will correspond to the value of the property. -Changing it will change the property (assuming the requested value -matches the requirements as specified in the #GParamSpec). - -Only the most common types are presently supported. Booleans are -mapped to booleans, strings to strings, signed/unsigned integers to -int32/uint32 and floats and doubles to doubles. - -If the property is an enum then the state will be string-typed and -conversion will automatically be performed between the enum value and -"nick" string as per the #GEnumValue table. - -Flags types are not currently supported. - -Properties of object types, boxed types and pointer types are not -supported and probably never will be. - -Properties of #GVariant types are not currently supported. - -If the property is boolean-valued then the action will have a NULL -parameter type, and activating the action (with no parameter) will -toggle the value of the property. - -In all other cases, the parameter type will correspond to the type of -the property. - -The general idea here is to reduce the number of locations where a -particular piece of state is kept (and therefore has to be synchronised -between). #GPropertyAction does not have a separate state that is kept -in sync with the property value -- its state is the property value. - -For example, it might be useful to create a #GAction corresponding to -the "visible-child-name" property of a #GtkStack so that the current -page can be switched from a menu. The active radio indication in the -menu is then directly determined from the active page of the -#GtkStack. - -An anti-example would be binding the "active-id" property on a -#GtkComboBox. This is because the state of the combobox itself is -probably uninteresting and is actually being used to control -something else. - -Another anti-example would be to bind to the "visible-child-name" -property of a #GtkStack if this value is actually stored in -#GSettings. In that case, the real source of the value is -#GSettings. If you want a #GAction to control a setting stored in -#GSettings, see g_settings_create_action() instead, and possibly -combine its use with g_settings_bind(). - - - Creates a #GAction corresponding to the value of property -@property_name on @object. - -The property must be existent and readable and writable (and not -construct-only). - -This function takes a reference on @object and doesn't release it -until the action is destroyed. - - - a new #GPropertyAction - - - - - the name of the action to create - - - - the object that has the property - to wrap - - - - the name of the property - - - - - - If @action is currently enabled. - -If the action is disabled then calls to g_action_activate() and -g_action_change_state() have no effect. - - - - If %TRUE, the state of the action will be the negation of the -property value, provided the property is boolean. - - - - The name of the action. This is mostly meaningful for identifying -the action once it has been added to a #GActionMap. - - - - The object to wrap a property on. - -The object must be a non-%NULL #GObject with properties. - - - - The type of the parameter that must be given when activating the -action. - - - - The name of the property to wrap on the object. - -The property must exist on the passed-in object and it must be -readable and writable (and not construct-only). - - - - The state of the action, or %NULL if the action is stateless. - - - - The #GVariantType of the state that the action has, or %NULL if the -action is stateless. - - - - - A #GProxy handles connecting to a remote host via a given type of -proxy server. It is implemented by the 'gio-proxy' extension point. -The extensions are named after their proxy protocol name. As an -example, a SOCKS5 proxy implementation can be retrieved with the -name 'socks5' using the function -g_io_extension_point_get_extension_by_name(). - - - Find the `gio-proxy` extension point for a proxy implementation that supports -the specified protocol. - - - return a #GProxy or NULL if protocol - is not supported. - - - - - the proxy protocol name (e.g. http, socks, etc) - - - - - - Given @connection to communicate with a proxy (eg, a -#GSocketConnection that is connected to the proxy server), this -does the necessary handshake to connect to @proxy_address, and if -required, wraps the #GIOStream to handle proxy payload. - - - a #GIOStream that will replace @connection. This might - be the same as @connection, in which case a reference - will be added. - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - - - Asynchronous version of g_proxy_connect(). - - - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - a #GAsyncReadyCallback - - - - callback data - - - - - - See g_proxy_connect(). - - - a #GIOStream. - - - - - a #GProxy - - - - a #GAsyncResult - - - - - - Some proxy protocols expect to be passed a hostname, which they -will resolve to an IP address themselves. Others, like SOCKS4, do -not allow this. This function will return %FALSE if @proxy is -implementing such a protocol. When %FALSE is returned, the caller -should resolve the destination hostname first, and then pass a -#GProxyAddress containing the stringified IP address to -g_proxy_connect() or g_proxy_connect_async(). - - - %TRUE if hostname resolution is supported. - - - - - a #GProxy - - - - - - Given @connection to communicate with a proxy (eg, a -#GSocketConnection that is connected to the proxy server), this -does the necessary handshake to connect to @proxy_address, and if -required, wraps the #GIOStream to handle proxy payload. - - - a #GIOStream that will replace @connection. This might - be the same as @connection, in which case a reference - will be added. - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - - - Asynchronous version of g_proxy_connect(). - - - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - a #GAsyncReadyCallback - - - - callback data - - - - - - See g_proxy_connect(). - - - a #GIOStream. - - - - - a #GProxy - - - - a #GAsyncResult - - - - - - Some proxy protocols expect to be passed a hostname, which they -will resolve to an IP address themselves. Others, like SOCKS4, do -not allow this. This function will return %FALSE if @proxy is -implementing such a protocol. When %FALSE is returned, the caller -should resolve the destination hostname first, and then pass a -#GProxyAddress containing the stringified IP address to -g_proxy_connect() or g_proxy_connect_async(). - - - %TRUE if hostname resolution is supported. - - - - - a #GProxy - - - - - - - Support for proxied #GInetSocketAddress. - - - - Creates a new #GProxyAddress for @inetaddr with @protocol that should -tunnel through @dest_hostname and @dest_port. - -(Note that this method doesn't set the #GProxyAddress:uri or -#GProxyAddress:destination-protocol fields; use g_object_new() -directly if you want to set those.) - - - a new #GProxyAddress - - - - - The proxy server #GInetAddress. - - - - The proxy server port. - - - - The proxy protocol to support, in lower case (e.g. socks, http). - - - - The destination hostname the proxy should tunnel to. - - - - The destination port to tunnel to. - - - - The username to authenticate to the proxy server - (or %NULL). - - - - The password to authenticate to the proxy server - (or %NULL). - - - - - - Gets @proxy's destination hostname; that is, the name of the host -that will be connected to via the proxy, not the name of the proxy -itself. - - - the @proxy's destination hostname - - - - - a #GProxyAddress - - - - - - Gets @proxy's destination port; that is, the port on the -destination host that will be connected to via the proxy, not the -port number of the proxy itself. - - - the @proxy's destination port - - - - - a #GProxyAddress - - - - - - Gets the protocol that is being spoken to the destination -server; eg, "http" or "ftp". - - - the @proxy's destination protocol - - - - - a #GProxyAddress - - - - - - Gets @proxy's password. - - - the @proxy's password - - - - - a #GProxyAddress - - - - - - Gets @proxy's protocol. eg, "socks" or "http" - - - the @proxy's protocol - - - - - a #GProxyAddress - - - - - - Gets the proxy URI that @proxy was constructed from. - - - the @proxy's URI, or %NULL if unknown - - - - - a #GProxyAddress - - - - - - Gets @proxy's username. - - - the @proxy's username - - - - - a #GProxyAddress - - - - - - - - - - - - The protocol being spoke to the destination host, or %NULL if -the #GProxyAddress doesn't know. - - - - - - - - - - The URI string that the proxy was constructed from (or %NULL -if the creator didn't specify this). - - - - - - - - - - - - - - Class structure for #GProxyAddress. - - - - - - - #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which -takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator -and wraps them in #GProxyAddress instances, using the given -#GProxyAddressEnumerator:proxy-resolver. - -This enumerator will be returned (for example, by -g_socket_connectable_enumerate()) as appropriate when a proxy is configured; -there should be no need to manually wrap a #GSocketAddressEnumerator instance -with one. - - - - - - The default port to use if #GProxyAddressEnumerator:uri does not -specify one. - - - - The proxy resolver to use. - - - - - - - - - - - - - - Class structure for #GProxyAddressEnumerator. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Provides an interface for handling proxy connection and payload. - - - The parent interface. - - - - - - - a #GIOStream that will replace @connection. This might - be the same as @connection, in which case a reference - will be added. - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - - - - - - - - - - - a #GProxy - - - - a #GIOStream - - - - a #GProxyAddress - - - - a #GCancellable - - - - a #GAsyncReadyCallback - - - - callback data - - - - - - - - - - a #GIOStream. - - - - - a #GProxy - - - - a #GAsyncResult - - - - - - - - - - %TRUE if hostname resolution is supported. - - - - - a #GProxy - - - - - - - - #GProxyResolver provides synchronous and asynchronous network proxy -resolution. #GProxyResolver is used within #GSocketClient through -the method g_socket_connectable_proxy_enumerate(). - -Implementations of #GProxyResolver based on libproxy and GNOME settings can -be found in glib-networking. GIO comes with an implementation for use inside -Flatpak portals. - - - Gets the default #GProxyResolver for the system. - - - the default #GProxyResolver. - - - - - Checks if @resolver can be used on this system. (This is used -internally; g_proxy_resolver_get_default() will only return a proxy -resolver that returns %TRUE for this method.) - - - %TRUE if @resolver is supported. - - - - - a #GProxyResolver - - - - - - Looks into the system proxy configuration to determine what proxy, -if any, to use to connect to @uri. The returned proxy URIs are of -the form `<protocol>://[user[:password]@]host:port` or -`direct://`, where <protocol> could be http, rtsp, socks -or other proxying protocol. - -If you don't know what network protocol is being used on the -socket, you should use `none` as the URI protocol. -In this case, the resolver might still return a generic proxy type -(such as SOCKS), but would not return protocol-specific proxy types -(such as http). - -`direct://` is used when no proxy is needed. -Direct connection should not be attempted unless it is part of the -returned array of proxies. - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - - - Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more -details. - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Call this function to obtain the array of proxy URIs when -g_proxy_resolver_lookup_async() is complete. See -g_proxy_resolver_lookup() for more details. - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Checks if @resolver can be used on this system. (This is used -internally; g_proxy_resolver_get_default() will only return a proxy -resolver that returns %TRUE for this method.) - - - %TRUE if @resolver is supported. - - - - - a #GProxyResolver - - - - - - Looks into the system proxy configuration to determine what proxy, -if any, to use to connect to @uri. The returned proxy URIs are of -the form `<protocol>://[user[:password]@]host:port` or -`direct://`, where <protocol> could be http, rtsp, socks -or other proxying protocol. - -If you don't know what network protocol is being used on the -socket, you should use `none` as the URI protocol. -In this case, the resolver might still return a generic proxy type -(such as SOCKS), but would not return protocol-specific proxy types -(such as http). - -`direct://` is used when no proxy is needed. -Direct connection should not be attempted unless it is part of the -returned array of proxies. - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - - - Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more -details. - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Call this function to obtain the array of proxy URIs when -g_proxy_resolver_lookup_async() is complete. See -g_proxy_resolver_lookup() for more details. - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - The virtual function table for #GProxyResolver. - - - The parent interface. - - - - - - - %TRUE if @resolver is supported. - - - - - a #GProxyResolver - - - - - - - - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GProxyResolver - - - - a URI representing the destination to connect to - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - - - - - A - NULL-terminated array of proxy URIs. Must be freed - with g_strfreev(). - - - - - - - a #GProxyResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Changes the size of the memory block pointed to by @data to -@size bytes. - -The function should have the same semantics as realloc(). - - - a pointer to the reallocated memory - - - - - memory block to reallocate - - - - size to reallocate @data to - - - - - - The GRemoteActionGroup interface is implemented by #GActionGroup -instances that either transmit action invocations to other processes -or receive action invocations in the local process from other -processes. - -The interface has `_full` variants of the two -methods on #GActionGroup used to activate actions: -g_action_group_activate_action() and -g_action_group_change_action_state(). These variants allow a -"platform data" #GVariant to be specified: a dictionary providing -context for the action invocation (for example: timestamps, startup -notification IDs, etc). - -#GDBusActionGroup implements #GRemoteActionGroup. This provides a -mechanism to send platform data for action invocations over D-Bus. - -Additionally, g_dbus_connection_export_action_group() will check if -the exported #GActionGroup implements #GRemoteActionGroup and use the -`_full` variants of the calls if available. This -provides a mechanism by which to receive platform data for action -invocations that arrive by way of D-Bus. - - - - Activates the remote action. - -This is the same as g_action_group_activate_action() except that it -allows for provision of "platform data" to be sent along with the -activation request. This typically contains details such as the user -interaction timestamp or startup notification information. - -@platform_data must be non-%NULL and must have the type -%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - - - - - - - a #GDBusActionGroup - - - - the name of the action to activate - - - - the optional parameter to the activation - - - - the platform data to send - - - - - - Changes the state of a remote action. - -This is the same as g_action_group_change_action_state() except that -it allows for provision of "platform data" to be sent along with the -state change request. This typically contains details such as the -user interaction timestamp or startup notification information. - -@platform_data must be non-%NULL and must have the type -%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - - - - - - - a #GRemoteActionGroup - - - - the name of the action to change the state of - - - - the new requested value for the state - - - - the platform data to send - - - - - - Activates the remote action. - -This is the same as g_action_group_activate_action() except that it -allows for provision of "platform data" to be sent along with the -activation request. This typically contains details such as the user -interaction timestamp or startup notification information. - -@platform_data must be non-%NULL and must have the type -%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - - - - - - - a #GDBusActionGroup - - - - the name of the action to activate - - - - the optional parameter to the activation - - - - the platform data to send - - - - - - Changes the state of a remote action. - -This is the same as g_action_group_change_action_state() except that -it allows for provision of "platform data" to be sent along with the -state change request. This typically contains details such as the -user interaction timestamp or startup notification information. - -@platform_data must be non-%NULL and must have the type -%G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - - - - - - - a #GRemoteActionGroup - - - - the name of the action to change the state of - - - - the new requested value for the state - - - - the platform data to send - - - - - - - The virtual function table for #GRemoteActionGroup. - - - - - - - - - - - - - a #GDBusActionGroup - - - - the name of the action to activate - - - - the optional parameter to the activation - - - - the platform data to send - - - - - - - - - - - - - - a #GRemoteActionGroup - - - - the name of the action to change the state of - - - - the new requested value for the state - - - - the platform data to send - - - - - - - - #GResolver provides cancellable synchronous and asynchronous DNS -resolution, for hostnames (g_resolver_lookup_by_address(), -g_resolver_lookup_by_name() and their async variants) and SRV -(service) records (g_resolver_lookup_service()). - -#GNetworkAddress and #GNetworkService provide wrappers around -#GResolver functionality that also implement #GSocketConnectable, -making it easy to connect to a remote host/service. - - - Frees @addresses (which should be the return value from -g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). -(This is a convenience method; you can also simply free the results -by hand.) - - - - - - - a #GList of #GInetAddress - - - - - - - - Frees @targets (which should be the return value from -g_resolver_lookup_service() or g_resolver_lookup_service_finish()). -(This is a convenience method; you can also simply free the -results by hand.) - - - - - - - a #GList of #GSrvTarget - - - - - - - - Gets the default #GResolver. You should unref it when you are done -with it. #GResolver may use its reference count as a hint about how -many threads it should allocate for concurrent DNS resolutions. - - - the default #GResolver. - - - - - Synchronously reverse-resolves @address to determine its -associated hostname. - -If the DNS resolution fails, @error (if non-%NULL) will be set to -a value from #GResolverError. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - - - a hostname (either ASCII-only, or in ASCII-encoded - form), or %NULL on error. - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously reverse-resolving @address to determine its -associated hostname, and eventually calls @callback, which must -call g_resolver_lookup_by_address_finish() to get the final result. - - - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_by_address_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a hostname (either ASCII-only, or in ASCII-encoded -form), or %NULL on error. - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Synchronously resolves @hostname to determine its associated IP -address(es). @hostname may be an ASCII-only or UTF-8 hostname, or -the textual form of an IP address (in which case this just becomes -a wrapper around g_inet_address_new_from_string()). - -On success, g_resolver_lookup_by_name() will return a non-empty #GList of -#GInetAddress, sorted in order of preference and guaranteed to not -contain duplicates. That is, if using the result to connect to -@hostname, you should attempt to connect to the first address -first, then the second if the first fails, etc. If you are using -the result to listen on a socket, it is appropriate to add each -result using e.g. g_socket_listener_add_address(). - -If the DNS resolution fails, @error (if non-%NULL) will be set to a -value from #GResolverError and %NULL will be returned. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - -If you are planning to connect to a socket on the resolved IP -address, it may be easier to create a #GNetworkAddress and use its -#GSocketConnectable interface. - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously resolving @hostname to determine its -associated IP address(es), and eventually calls @callback, which -must call g_resolver_lookup_by_name_finish() to get the result. -See g_resolver_lookup_by_name() for more details. - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a call to -g_resolver_lookup_by_name_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - This differs from g_resolver_lookup_by_name() in that you can modify -the lookup behavior with @flags. For example this can be used to limit -results with #G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously resolving @hostname to determine its -associated IP address(es), and eventually calls @callback, which -must call g_resolver_lookup_by_name_with_flags_finish() to get the result. -See g_resolver_lookup_by_name() for more details. - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a call to -g_resolver_lookup_by_name_with_flags_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Synchronously performs a DNS record lookup for the given @rrname and returns -a list of records as #GVariant tuples. See #GResolverRecordType for -information on what the records contain for each @record_type. - -If the DNS resolution fails, @error (if non-%NULL) will be set to -a value from #GResolverError and %NULL will be returned. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously performing a DNS lookup for the given -@rrname, and eventually calls @callback, which must call -g_resolver_lookup_records_finish() to get the final result. See -g_resolver_lookup_records() for more details. - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_records_async(). Returns a non-empty list of records as -#GVariant tuples. See #GResolverRecordType for information on what the -records contain. - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_service_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more -details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - - - - Synchronously reverse-resolves @address to determine its -associated hostname. - -If the DNS resolution fails, @error (if non-%NULL) will be set to -a value from #GResolverError. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - - - a hostname (either ASCII-only, or in ASCII-encoded - form), or %NULL on error. - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously reverse-resolving @address to determine its -associated hostname, and eventually calls @callback, which must -call g_resolver_lookup_by_address_finish() to get the final result. - - - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_by_address_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a hostname (either ASCII-only, or in ASCII-encoded -form), or %NULL on error. - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Synchronously resolves @hostname to determine its associated IP -address(es). @hostname may be an ASCII-only or UTF-8 hostname, or -the textual form of an IP address (in which case this just becomes -a wrapper around g_inet_address_new_from_string()). - -On success, g_resolver_lookup_by_name() will return a non-empty #GList of -#GInetAddress, sorted in order of preference and guaranteed to not -contain duplicates. That is, if using the result to connect to -@hostname, you should attempt to connect to the first address -first, then the second if the first fails, etc. If you are using -the result to listen on a socket, it is appropriate to add each -result using e.g. g_socket_listener_add_address(). - -If the DNS resolution fails, @error (if non-%NULL) will be set to a -value from #GResolverError and %NULL will be returned. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - -If you are planning to connect to a socket on the resolved IP -address, it may be easier to create a #GNetworkAddress and use its -#GSocketConnectable interface. - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously resolving @hostname to determine its -associated IP address(es), and eventually calls @callback, which -must call g_resolver_lookup_by_name_finish() to get the result. -See g_resolver_lookup_by_name() for more details. - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a call to -g_resolver_lookup_by_name_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - This differs from g_resolver_lookup_by_name() in that you can modify -the lookup behavior with @flags. For example this can be used to limit -results with #G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously resolving @hostname to determine its -associated IP address(es), and eventually calls @callback, which -must call g_resolver_lookup_by_name_with_flags_finish() to get the result. -See g_resolver_lookup_by_name() for more details. - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a call to -g_resolver_lookup_by_name_with_flags_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Synchronously performs a DNS record lookup for the given @rrname and returns -a list of records as #GVariant tuples. See #GResolverRecordType for -information on what the records contain for each @record_type. - -If the DNS resolution fails, @error (if non-%NULL) will be set to -a value from #GResolverError and %NULL will be returned. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously performing a DNS lookup for the given -@rrname, and eventually calls @callback, which must call -g_resolver_lookup_records_finish() to get the final result. See -g_resolver_lookup_records() for more details. - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_records_async(). Returns a non-empty list of records as -#GVariant tuples. See #GResolverRecordType for information on what the -records contain. - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Synchronously performs a DNS SRV lookup for the given @service and -@protocol in the given @domain and returns an array of #GSrvTarget. -@domain may be an ASCII-only or UTF-8 hostname. Note also that the -@service and @protocol arguments do not include the leading underscore -that appears in the actual DNS entry. - -On success, g_resolver_lookup_service() will return a non-empty #GList of -#GSrvTarget, sorted in order of preference. (That is, you should -attempt to connect to the first target first, then the second if -the first fails, etc.) - -If the DNS resolution fails, @error (if non-%NULL) will be set to -a value from #GResolverError and %NULL will be returned. - -If @cancellable is non-%NULL, it can be used to cancel the -operation, in which case @error (if non-%NULL) will be set to -%G_IO_ERROR_CANCELLED. - -If you are planning to connect to the service, it is usually easier -to create a #GNetworkService and use its #GSocketConnectable -interface. - - - a non-empty #GList of -#GSrvTarget, or %NULL on error. You must free each of the targets and the -list when you are done with it. (You can use g_resolver_free_targets() to do -this.) - - - - - - - a #GResolver - - - - the service type to look up (eg, "ldap") - - - - the networking protocol to use for @service (eg, "tcp") - - - - the DNS domain to look up the service in - - - - a #GCancellable, or %NULL - - - - - - Begins asynchronously performing a DNS SRV lookup for the given -@service and @protocol in the given @domain, and eventually calls -@callback, which must call g_resolver_lookup_service_finish() to -get the final result. See g_resolver_lookup_service() for more -details. - - - - - - - a #GResolver - - - - the service type to look up (eg, "ldap") - - - - the networking protocol to use for @service (eg, "tcp") - - - - the DNS domain to look up the service in - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - Retrieves the result of a previous call to -g_resolver_lookup_service_async(). - -If the DNS resolution failed, @error (if non-%NULL) will be set to -a value from #GResolverError. If the operation was cancelled, -@error will be set to %G_IO_ERROR_CANCELLED. - - - a non-empty #GList of -#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more -details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - Sets @resolver to be the application's default resolver (reffing -@resolver, and unreffing the previous default resolver, if any). -Future calls to g_resolver_get_default() will return this resolver. - -This can be used if an application wants to perform any sort of DNS -caching or "pinning"; it can implement its own #GResolver that -calls the original default resolver for DNS operations, and -implements its own cache policies on top of that, and then set -itself as the default resolver for all later code to use. - - - - - - - the new default #GResolver - - - - - - - - - - - - Emitted when the resolver notices that the system resolver -configuration has changed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - - - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - a hostname (either ASCII-only, or in ASCII-encoded - form), or %NULL on error. - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GResolver - - - - the address to reverse-resolve - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - - - - - a hostname (either ASCII-only, or in ASCII-encoded -form), or %NULL on error. - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a non-empty #GList of -#GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more -details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GResolver - - - - the DNS name to look up the record for - - - - the type of DNS record to look up - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - - - - - a non-empty #GList of -#GVariant, or %NULL on error. You must free each of the records and the list -when you are done with it. (You can use g_list_free_full() with -g_variant_unref() to do this.) - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - a #GResolver - - - - the hostname to look up the address of - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - callback to call after resolution completes - - - - data for @callback - - - - - - - - - - a #GList -of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() -for more details. - - - - - - - a #GResolver - - - - the result passed to your #GAsyncReadyCallback - - - - - - - - - - a non-empty #GList -of #GInetAddress, or %NULL on error. You -must unref each of the addresses and free the list when you are -done with it. (You can use g_resolver_free_addresses() to do this.) - - - - - - - a #GResolver - - - - the hostname to look up - - - - extra #GResolverNameLookupFlags for the lookup - - - - a #GCancellable, or %NULL - - - - - - - - An error code used with %G_RESOLVER_ERROR in a #GError returned -from a #GResolver routine. - - the requested name/address/service was not - found - - - the requested information could not - be looked up due to a network error or similar problem - - - unknown error - - - Gets the #GResolver Error Quark. - - a #GQuark. - - - - - - Flags to modify lookup behavior. - - default behavior (same as g_resolver_lookup_by_name()) - - - only resolve ipv4 addresses - - - only resolve ipv6 addresses - - - - - - - The type of record that g_resolver_lookup_records() or -g_resolver_lookup_records_async() should retrieve. The records are returned -as lists of #GVariant tuples. Each record type has different values in -the variant tuples returned. - -%G_RESOLVER_RECORD_SRV records are returned as variants with the signature -`(qqqs)`, containing a `guint16` with the priority, a `guint16` with the -weight, a `guint16` with the port, and a string of the hostname. - -%G_RESOLVER_RECORD_MX records are returned as variants with the signature -`(qs)`, representing a `guint16` with the preference, and a string containing -the mail exchanger hostname. - -%G_RESOLVER_RECORD_TXT records are returned as variants with the signature -`(as)`, representing an array of the strings in the text record. Note: Most TXT -records only contain a single string, but -[RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a -record to contain multiple strings. The RFC which defines the interpretation -of a specific TXT record will likely require concatenation of multiple -strings if they are present, as with -[RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3). - -%G_RESOLVER_RECORD_SOA records are returned as variants with the signature -`(ssuuuuu)`, representing a string containing the primary name server, a -string containing the administrator, the serial as a `guint32`, the refresh -interval as a `guint32`, the retry interval as a `guint32`, the expire timeout -as a `guint32`, and the TTL as a `guint32`. - -%G_RESOLVER_RECORD_NS records are returned as variants with the signature -`(s)`, representing a string of the hostname of the name server. - - look up DNS SRV records for a domain - - - look up DNS MX records for a domain - - - look up DNS TXT records for a name - - - look up DNS SOA records for a zone - - - look up DNS NS records for a domain - - - - Applications and libraries often contain binary or textual data that is -really part of the application, rather than user data. For instance -#GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, -icons, etc. These are often shipped as files in `$datadir/appname`, or -manually included as literal strings in the code. - -The #GResource API and the [glib-compile-resources][glib-compile-resources] program -provide a convenient and efficient alternative to this which has some nice properties. You -maintain the files as normal files, so its easy to edit them, but during the build the files -are combined into a binary bundle that is linked into the executable. This means that loading -the resource files are efficient (as they are already in memory, shared with other instances) and -simple (no need to check for things like I/O errors or locate the files in the filesystem). It -also makes it easier to create relocatable applications. - -Resource files can also be marked as compressed. Such files will be included in the resource bundle -in a compressed form, but will be automatically uncompressed when the resource is used. This -is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. - -Resource files can also be marked to be preprocessed, by setting the value of the -`preprocess` attribute to a comma-separated list of preprocessing options. -The only options currently supported are: - -`xml-stripblanks` which will use the xmllint command -to strip ignorable whitespace from the XML file. For this to work, -the `XMLLINT` environment variable must be set to the full path to -the xmllint executable, or xmllint must be in the `PATH`; otherwise -the preprocessing step is skipped. - -`to-pixdata` which will use the gdk-pixbuf-pixdata command to convert -images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside -the resource file, rather than an (uncompressed) copy of it. For this, the gdk-pixbuf-pixdata -program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be -set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will -abort. - -Resource files will be exported in the GResource namespace using the -combination of the given `prefix` and the filename from the `file` element. -The `alias` attribute can be used to alter the filename to expose them at a -different location in the resource namespace. Typically, this is used to -include files from a different source directory without exposing the source -directory in the resource namespace, as in the example below. - -Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program -which takes an XML file that describes the bundle, and a set of files that the XML references. These -are combined into a binary resource bundle. - -An example resource description: -|[ -<?xml version="1.0" encoding="UTF-8"?> -<gresources> - <gresource prefix="/org/gtk/Example"> - <file>data/splashscreen.png</file> - <file compressed="true">dialog.ui</file> - <file preprocess="xml-stripblanks">menumarkup.xml</file> - <file alias="example.css">data/example.css</file> - </gresource> -</gresources> -]| - -This will create a resource bundle with the following files: -|[ -/org/gtk/Example/data/splashscreen.png -/org/gtk/Example/dialog.ui -/org/gtk/Example/menumarkup.xml -/org/gtk/Example/example.css -]| - -Note that all resources in the process share the same namespace, so use Java-style -path prefixes (like in the above example) to avoid conflicts. - -You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a -binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and ---generate-header arguments to create a source file and header to link directly into your application. -This will generate `get_resource()`, `register_resource()` and -`unregister_resource()` functions, prefixed by the `--c-name` argument passed -to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns -the generated #GResource object. The register and unregister functions -register the resource so its files can be accessed using -g_resources_lookup_data(). - -Once a #GResource has been created and registered all the data in it can be accessed globally in the process by -using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer -to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access -the resource data. - -Some higher-level APIs, such as #GtkApplication, will automatically load -resources from certain well-known paths in the resource namespace as a -convenience. See the documentation for those APIs for details. - -There are two forms of the generated source, the default version uses the compiler support for constructor -and destructor functions (where available) to automatically create and register the #GResource on startup -or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created -instead. This requires an explicit initialization call in your application/library, but it works on all platforms, -even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) - -Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries -during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away -when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses -are for your own resources, and resource data is often used once, during parsing, and then released. - -When debugging a program or testing a change to an installed version, it is often useful to be able to -replace resources in the program or library, without recompiling, for debugging or quick hacking and testing -purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay -resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform -during resource lookups. - -A substitution has the form - -|[ - /org/gtk/libgtk=/home/desrt/gtk-overlay -]| - -The part before the `=` is the resource subpath for which the overlay applies. The part after is a -filesystem path which contains files and subdirectories as you would like to be loaded as resources with the -equivalent names. - -In the example above, if an application tried to load a resource with the resource path -`/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path -`/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an -overlay, not an outright replacement, which means that if a file is not found at that path, the built-in -version will be used instead. Whiteouts are not currently supported. - -Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after -the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the -location of a single resource with an individual file. - - - Creates a GResource from a reference to the binary resource bundle. -This will keep a reference to @data while the resource lives, so -the data should not be modified or freed. - -If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). - -Note: @data must be backed by memory that is at least pointer aligned. -Otherwise this function will internally create a copy of the memory since -GLib 2.56, or in older versions fail and exit the process. - -If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. - - - a new #GResource, or %NULL on error - - - - - A #GBytes - - - - - - Registers the resource with the process-global set of resources. -Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). - - - - - - - A #GResource - - - - - - Unregisters the resource from the process-global set of resources. - - - - - - - A #GResource - - - - - - Returns all the names of children at the specified @path in the resource. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). - -If @path is invalid or does not exist in the #GResource, -%G_RESOURCE_ERROR_NOT_FOUND will be returned. - -@lookup_flags controls the behaviour of the lookup. - - - an array of constant strings - - - - - - - A #GResource - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Looks for a file at the specified @path in the resource and -if found returns information about it. - -@lookup_flags controls the behaviour of the lookup. - - - %TRUE if the file was found. %FALSE if there were errors - - - - - A #GResource - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - a location to place the length of the contents of the file, - or %NULL if the length is not needed - - - - a location to place the flags about the file, - or %NULL if the length is not needed - - - - - - Looks for a file at the specified @path in the resource and -returns a #GBytes that lets you directly access the data in -memory. - -The data is always followed by a zero byte, so you -can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. - -For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section -in the program binary. For compressed files we allocate memory on -the heap and automatically uncompress the data. - -@lookup_flags controls the behaviour of the lookup. - - - #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() - - - - - A #GResource - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Looks for a file at the specified @path in the resource and -returns a #GInputStream that lets you read the data. - -@lookup_flags controls the behaviour of the lookup. - - - #GInputStream or %NULL on error. - Free the returned object with g_object_unref() - - - - - A #GResource - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Atomically increments the reference count of @resource by one. This -function is MT-safe and may be called from any thread. - - - The passed in #GResource - - - - - A #GResource - - - - - - Atomically decrements the reference count of @resource by one. If the -reference count drops to 0, all memory allocated by the resource is -released. This function is MT-safe and may be called from any -thread. - - - - - - - A #GResource - - - - - - Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. - -If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). - -If @filename is empty or the data in it is corrupt, -%G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. - - - a new #GResource, or %NULL on error - - - - - the path of a filename to load, in the GLib filename encoding - - - - - - - An error code used with %G_RESOURCE_ERROR in a #GError returned -from a #GResource routine. - - no file was found at the requested path - - - unknown error - - - Gets the #GResource Error Quark. - - a #GQuark - - - - - - GResourceFlags give information about a particular file inside a resource -bundle. - - No flags set. - - - The file is compressed. - - - - GResourceLookupFlags determine how resource path lookups are handled. - - No flags set. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for #GSettingsBackend functionality. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GSeekable is implemented by streams (implementations of -#GInputStream or #GOutputStream) that support seeking. - -Seekable streams largely fall into two categories: resizable and -fixed-size. - -#GSeekable on fixed-sized streams is approximately the same as POSIX -lseek() on a block device (for example: attempting to seek past the -end of the device is an error). Fixed streams typically cannot be -truncated. - -#GSeekable on resizable streams is approximately the same as POSIX -lseek() on a normal file. Seeking past the end and writing data will -usually cause the stream to resize by introducing zero bytes. - - - Tests if the stream supports the #GSeekableIface. - - - %TRUE if @seekable can be seeked. %FALSE otherwise. - - - - - a #GSeekable. - - - - - - Tests if the length of the stream can be adjusted with -g_seekable_truncate(). - - - %TRUE if the stream can be truncated, %FALSE otherwise. - - - - - a #GSeekable. - - - - - - Seeks in the stream by the given @offset, modified by @type. - -Attempting to seek past the end of the stream will have different -results depending on if the stream is fixed-sized or resizable. If -the stream is resizable then seeking past the end and then writing -will result in zeros filling the empty space. Seeking past the end -of a resizable stream and reading will result in EOF. Seeking past -the end of a fixed-sized stream will fail. - -Any operation that would result in a negative offset will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - a #goffset. - - - - a #GSeekType. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tells the current position within the stream. - - - the offset from the beginning of the buffer. - - - - - a #GSeekable. - - - - - - Sets the length of the stream to @offset. If the stream was previously -larger than @offset, the extra data is discarded. If the stream was -previouly shorter than @offset, it is extended with NUL ('\0') bytes. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - new length for @seekable, in bytes. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tests if the stream supports the #GSeekableIface. - - - %TRUE if @seekable can be seeked. %FALSE otherwise. - - - - - a #GSeekable. - - - - - - Tests if the length of the stream can be adjusted with -g_seekable_truncate(). - - - %TRUE if the stream can be truncated, %FALSE otherwise. - - - - - a #GSeekable. - - - - - - Seeks in the stream by the given @offset, modified by @type. - -Attempting to seek past the end of the stream will have different -results depending on if the stream is fixed-sized or resizable. If -the stream is resizable then seeking past the end and then writing -will result in zeros filling the empty space. Seeking past the end -of a resizable stream and reading will result in EOF. Seeking past -the end of a fixed-sized stream will fail. - -Any operation that would result in a negative offset will fail. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - a #goffset. - - - - a #GSeekType. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tells the current position within the stream. - - - the offset from the beginning of the buffer. - - - - - a #GSeekable. - - - - - - Sets the length of the stream to @offset. If the stream was previously -larger than @offset, the extra data is discarded. If the stream was -previouly shorter than @offset, it is extended with NUL ('\0') bytes. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the -partial result will be returned, without an error. - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - new length for @seekable, in bytes. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - Provides an interface for implementing seekable functionality on I/O Streams. - - - The parent interface. - - - - - - - the offset from the beginning of the buffer. - - - - - a #GSeekable. - - - - - - - - - - %TRUE if @seekable can be seeked. %FALSE otherwise. - - - - - a #GSeekable. - - - - - - - - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - a #goffset. - - - - a #GSeekType. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - %TRUE if the stream can be truncated, %FALSE otherwise. - - - - - a #GSeekable. - - - - - - - - - - %TRUE if successful. If an error - has occurred, this function will return %FALSE and set @error - appropriately if present. - - - - - a #GSeekable. - - - - new length for @seekable, in bytes. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - The #GSettings class provides a convenient API for storing and retrieving -application settings. - -Reads and writes can be considered to be non-blocking. Reading -settings with #GSettings is typically extremely fast: on -approximately the same order of magnitude (but slower than) a -#GHashTable lookup. Writing settings is also extremely fast in terms -of time to return to your application, but can be extremely expensive -for other threads and other processes. Many settings backends -(including dconf) have lazy initialisation which means in the common -case of the user using their computer without modifying any settings -a lot of work can be avoided. For dconf, the D-Bus service doesn't -even need to be started in this case. For this reason, you should -only ever modify #GSettings keys in response to explicit user action. -Particular care should be paid to ensure that modifications are not -made during startup -- for example, when setting the initial value -of preferences widgets. The built-in g_settings_bind() functionality -is careful not to write settings in response to notify signals as a -result of modifications that it makes to widgets. - -When creating a GSettings instance, you have to specify a schema -that describes the keys in your settings and their types and default -values, as well as some other information. - -Normally, a schema has a fixed path that determines where the settings -are stored in the conceptual global tree of settings. However, schemas -can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with -a fixed path. This is -useful e.g. when the schema describes an 'account', and you want to be -able to store a arbitrary number of accounts. - -Paths must start with and end with a forward slash character ('/') -and must not contain two sequential slash characters. Paths should -be chosen based on a domain name associated with the program or -library to which the settings belong. Examples of paths are -"/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". -Paths should not start with "/apps/", "/desktop/" or "/system/" as -they often did in GConf. - -Unlike other configuration systems (like GConf), GSettings does not -restrict keys to basic types like strings and numbers. GSettings stores -values as #GVariant, and allows any #GVariantType for keys. Key names -are restricted to lowercase characters, numbers and '-'. Furthermore, -the names must begin with a lowercase character, must not end -with a '-', and must not contain consecutive dashes. - -Similar to GConf, the default values in GSettings schemas can be -localized, but the localized values are stored in gettext catalogs -and looked up with the domain that is specified in the -`gettext-domain` attribute of the <schemalist> or <schema> -elements and the category that is specified in the `l10n` attribute of -the <default> element. The string which is translated includes all text in -the <default> element, including any surrounding quotation marks. - -The `l10n` attribute must be set to `messages` or `time`, and sets the -[locale category for -translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). -The `messages` category should be used by default; use `time` for -translatable date or time formats. A translation comment can be added as an -XML comment immediately above the <default> element — it is recommended to -add these comments to aid translators understand the meaning and -implications of the default value. An optional translation `context` -attribute can be set on the <default> element to disambiguate multiple -defaults which use the same string. - -For example: -|[ - <!-- Translators: A list of words which are not allowed to be typed, in - GVariant serialization syntax. - See: https://developer.gnome.org/glib/stable/gvariant-text.html --> - <default l10n='messages' context='Banned words'>['bad', 'words']</default> -]| - -Translations of default values must remain syntactically valid serialized -#GVariants (e.g. retaining any surrounding quotation marks) or runtime -errors will occur. - -GSettings uses schemas in a compact binary form that is created -by the [glib-compile-schemas][glib-compile-schemas] -utility. The input is a schema description in an XML format. - -A DTD for the gschema XML format can be found here: -[gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) - -The [glib-compile-schemas][glib-compile-schemas] tool expects schema -files to have the extension `.gschema.xml`. - -At runtime, schemas are identified by their id (as specified in the -id attribute of the <schema> element). The convention for schema -ids is to use a dotted name, similar in style to a D-Bus bus name, -e.g. "org.gnome.SessionManager". In particular, if the settings are -for a specific service that owns a D-Bus bus name, the D-Bus bus name -and schema id should match. For schemas which deal with settings not -associated with one named application, the id should not use -StudlyCaps, e.g. "org.gnome.font-rendering". - -In addition to #GVariant types, keys can have types that have -enumerated types. These can be described by a <choice>, -<enum> or <flags> element, as seen in the -[example][schema-enumerated]. The underlying type of such a key -is string, but you can use g_settings_get_enum(), g_settings_set_enum(), -g_settings_get_flags(), g_settings_set_flags() access the numeric values -corresponding to the string value of enum and flags keys. - -An example for default value: -|[ -<schemalist> - <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> - - <key name="greeting" type="s"> - <default l10n="messages">"Hello, earthlings"</default> - <summary>A greeting</summary> - <description> - Greeting of the invading martians - </description> - </key> - - <key name="box" type="(ii)"> - <default>(20,30)</default> - </key> - - <key name="empty-string" type="s"> - <default>""</default> - <summary>Empty strings have to be provided in GVariant form</summary> - </key> - - </schema> -</schemalist> -]| - -An example for ranges, choices and enumerated types: -|[ -<schemalist> - - <enum id="org.gtk.Test.myenum"> - <value nick="first" value="1"/> - <value nick="second" value="2"/> - </enum> - - <flags id="org.gtk.Test.myflags"> - <value nick="flag1" value="1"/> - <value nick="flag2" value="2"/> - <value nick="flag3" value="4"/> - </flags> - - <schema id="org.gtk.Test"> - - <key name="key-with-range" type="i"> - <range min="1" max="100"/> - <default>10</default> - </key> - - <key name="key-with-choices" type="s"> - <choices> - <choice value='Elisabeth'/> - <choice value='Annabeth'/> - <choice value='Joe'/> - </choices> - <aliases> - <alias value='Anna' target='Annabeth'/> - <alias value='Beth' target='Elisabeth'/> - </aliases> - <default>'Joe'</default> - </key> - - <key name='enumerated-key' enum='org.gtk.Test.myenum'> - <default>'first'</default> - </key> - - <key name='flags-key' flags='org.gtk.Test.myflags'> - <default>["flag1","flag2"]</default> - </key> - </schema> -</schemalist> -]| - -## Vendor overrides - -Default values are defined in the schemas that get installed by -an application. Sometimes, it is necessary for a vendor or distributor -to adjust these defaults. Since patching the XML source for the schema -is inconvenient and error-prone, -[glib-compile-schemas][glib-compile-schemas] reads so-called vendor -override' files. These are keyfiles in the same directory as the XML -schema sources which can override default values. The schema id serves -as the group name in the key file, and the values are expected in -serialized GVariant form, as in the following example: -|[ - [org.gtk.Example] - key1='string' - key2=1.5 -]| - -glib-compile-schemas expects schema files to have the extension -`.gschema.override`. - -## Binding - -A very convenient feature of GSettings lets you bind #GObject properties -directly to settings, using g_settings_bind(). Once a GObject property -has been bound to a setting, changes on either side are automatically -propagated to the other side. GSettings handles details like mapping -between GObject and GVariant types, and preventing infinite cycles. - -This makes it very easy to hook up a preferences dialog to the -underlying settings. To make this even more convenient, GSettings -looks for a boolean property with the name "sensitivity" and -automatically binds it to the writability of the bound setting. -If this 'magic' gets in the way, it can be suppressed with the -#G_SETTINGS_BIND_NO_SENSITIVITY flag. - -## Relocatable schemas # {#gsettings-relocatable} - -A relocatable schema is one with no `path` attribute specified on its -<schema> element. By using g_settings_new_with_path(), a #GSettings object -can be instantiated for a relocatable schema, assigning a path to the -instance. Paths passed to g_settings_new_with_path() will typically be -constructed dynamically from a constant prefix plus some form of instance -identifier; but they must still be valid GSettings paths. Paths could also -be constant and used with a globally installed schema originating from a -dependency library. - -For example, a relocatable schema could be used to store geometry information -for different windows in an application. If the schema ID was -`org.foo.MyApp.Window`, it could be instantiated for paths -`/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, -`/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known -they can be specified as <child> elements in the parent schema, e.g.: -|[ -<schema id="org.foo.MyApp" path="/org/foo/MyApp/"> - <child name="main" schema="org.foo.MyApp.Window"/> -</schema> -]| - -## Build system integration # {#gsettings-build-system} - -GSettings comes with autotools integration to simplify compiling and -installing schemas. To add GSettings support to an application, add the -following to your `configure.ac`: -|[ -GLIB_GSETTINGS -]| - -In the appropriate `Makefile.am`, use the following snippet to compile and -install the named schema: -|[ -gsettings_SCHEMAS = org.foo.MyApp.gschema.xml -EXTRA_DIST = $(gsettings_SCHEMAS) - -@GSETTINGS_RULES@ -]| - -No changes are needed to the build system to mark a schema XML file for -translation. Assuming it sets the `gettext-domain` attribute, a schema may -be marked for translation by adding it to `POTFILES.in`, assuming gettext -0.19 is in use (the preferred method for translation): -|[ -data/org.foo.MyApp.gschema.xml -]| - -Alternatively, if intltool 0.50.1 is in use: -|[ -[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml -]| - -GSettings will use gettext to look up translations for the <summary> and -<description> elements, and also any <default> elements which have a `l10n` -attribute set. Translations must not be included in the `.gschema.xml` file -by the build system, for example by using intltool XML rules with a -`.gschema.xml.in` template. - -If an enumerated type defined in a C header file is to be used in a GSettings -schema, it can either be defined manually using an <enum> element in the -schema XML, or it can be extracted automatically from the C header. This -approach is preferred, as it ensures the two representations are always -synchronised. To do so, add the following to the relevant `Makefile.am`: -|[ -gsettings_ENUM_NAMESPACE = org.foo.MyApp -gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h -]| - -`gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, -which are specified in `gsettings_ENUM_FILES`. This will generate a -`org.foo.MyApp.enums.xml` file containing the extracted enums, which will be -automatically included in the schema compilation, install and uninstall -rules. It should not be committed to version control or included in -`EXTRA_DIST`. - - - Creates a new #GSettings object with the schema specified by -@schema_id. - -Signals on the newly created #GSettings object will be dispatched -via the thread-default #GMainContext in effect at the time of the -call to g_settings_new(). The new #GSettings will hold a reference -on the context. See g_main_context_push_thread_default(). - - - a new #GSettings object - - - - - the id of the schema - - - - - - Creates a new #GSettings object with a given schema, backend and -path. - -It should be extremely rare that you ever want to use this function. -It is made available for advanced use-cases (such as plugin systems -that want to provide access to schemas loaded from custom locations, -etc). - -At the most basic level, a #GSettings object is a pure composition of -4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that -backend, and a #GMainContext to which signals are dispatched. - -This constructor therefore gives you full control over constructing -#GSettings instances. The first 3 parameters are given directly as -@schema, @backend and @path, and the main context is taken from the -thread-default (as per g_settings_new()). - -If @backend is %NULL then the default backend is used. - -If @path is %NULL then the path from the schema is used. It is an -error if @path is %NULL and the schema has no path of its own or if -@path is non-%NULL and not equal to the path that the schema does -have. - - - a new #GSettings object - - - - - a #GSettingsSchema - - - - a #GSettingsBackend - - - - the path to use - - - - - - Creates a new #GSettings object with the schema specified by -@schema_id and a given #GSettingsBackend. - -Creating a #GSettings object with a different backend allows accessing -settings from a database other than the usual one. For example, it may make -sense to pass a backend corresponding to the "defaults" settings database on -the system to get a settings object that modifies the system default -settings instead of the settings for this user. - - - a new #GSettings object - - - - - the id of the schema - - - - the #GSettingsBackend to use - - - - - - Creates a new #GSettings object with the schema specified by -@schema_id and a given #GSettingsBackend and path. - -This is a mix of g_settings_new_with_backend() and -g_settings_new_with_path(). - - - a new #GSettings object - - - - - the id of the schema - - - - the #GSettingsBackend to use - - - - the path to use - - - - - - Creates a new #GSettings object with the relocatable schema specified -by @schema_id and a given path. - -You only need to do this if you want to directly create a settings -object with a schema that doesn't have a specified path of its own. -That's quite rare. - -It is a programmer error to call this function for a schema that -has an explicitly specified path. - -It is a programmer error if @path is not a valid path. A valid path -begins and ends with '/' and does not contain two consecutive '/' -characters. - - - a new #GSettings object - - - - - the id of the schema - - - - the path to use - - - - - - Deprecated. - Use g_settings_schema_source_list_schemas() instead - - - a list of relocatable - #GSettings schemas that are available, in no defined order. The list must - not be modified or freed. - - - - - - - Deprecated. - Use g_settings_schema_source_list_schemas() instead. -If you used g_settings_list_schemas() to check for the presence of -a particular schema, use g_settings_schema_source_lookup() instead -of your whole loop. - - - a list of #GSettings - schemas that are available, in no defined order. The list must not be - modified or freed. - - - - - - - Ensures that all pending operations are complete for the default backend. - -Writes made to a #GSettings are handled asynchronously. For this -reason, it is very unlikely that the changes have it to disk by the -time g_settings_set() returns. - -This call will block until all of the writes have made it to the -backend. Since the mainloop is not running, no change notifications -will be dispatched during this call (but some may be queued by the -time the call is done). - - - - - - - Removes an existing binding for @property on @object. - -Note that bindings are automatically removed when the -object is finalized, so it is rarely necessary to call this -function. - - - - - - - the object - - - - the property whose binding is removed - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Applies any changes that have been made to the settings. This -function does nothing unless @settings is in 'delay-apply' mode; -see g_settings_delay(). In the normal case settings are always -applied immediately. - - - - - - - a #GSettings instance - - - - - - Create a binding between the @key in the @settings object -and the property @property of @object. - -The binding uses the default GIO mapping functions to map -between the settings and property values. These functions -handle booleans, numeric types and string types in a -straightforward way. Use g_settings_bind_with_mapping() if -you need a custom mapping, or map between types that are not -supported by the default mapping functions. - -Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this -function also establishes a binding between the writability of -@key and the "sensitive" property of @object (if @object has -a boolean property by that name). See g_settings_bind_writable() -for more details about writable bindings. - -Note that the lifecycle of the binding is tied to @object, -and that you can have only one binding per object property. -If you bind the same property twice on the same object, the second -binding overrides the first one. - - - - - - - a #GSettings object - - - - the key to bind - - - - a #GObject - - - - the name of the property to bind - - - - flags for the binding - - - - - - Create a binding between the @key in the @settings object -and the property @property of @object. - -The binding uses the provided mapping functions to map between -settings and property values. - -Note that the lifecycle of the binding is tied to @object, -and that you can have only one binding per object property. -If you bind the same property twice on the same object, the second -binding overrides the first one. - - - - - - - a #GSettings object - - - - the key to bind - - - - a #GObject - - - - the name of the property to bind - - - - flags for the binding - - - - a function that gets called to convert values - from @settings to @object, or %NULL to use the default GIO mapping - - - - a function that gets called to convert values - from @object to @settings, or %NULL to use the default GIO mapping - - - - data that gets passed to @get_mapping and @set_mapping - - - - #GDestroyNotify function for @user_data - - - - - - Create a binding between the writability of @key in the -@settings object and the property @property of @object. -The property must be boolean; "sensitive" or "visible" -properties of widgets are the most likely candidates. - -Writable bindings are always uni-directional; changes of the -writability of the setting will be propagated to the object -property, not the other way. - -When the @inverted argument is %TRUE, the binding inverts the -value as it passes from the setting to the object, i.e. @property -will be set to %TRUE if the key is not writable. - -Note that the lifecycle of the binding is tied to @object, -and that you can have only one binding per object property. -If you bind the same property twice on the same object, the second -binding overrides the first one. - - - - - - - a #GSettings object - - - - the key to bind - - - - a #GObject - - - - the name of a boolean property to bind - - - - whether to 'invert' the value - - - - - - Creates a #GAction corresponding to a given #GSettings key. - -The action has the same name as the key. - -The value of the key becomes the state of the action and the action -is enabled when the key is writable. Changing the state of the -action results in the key being written to. Changes to the value or -writability of the key cause appropriate change notifications to be -emitted for the action. - -For boolean-valued keys, action activations take no parameter and -result in the toggling of the value. For all other types, -activations take the new value for the key (which must have the -correct type). - - - a new #GAction - - - - - a #GSettings - - - - the name of a key in @settings - - - - - - Changes the #GSettings object into 'delay-apply' mode. In this -mode, changes to @settings are not immediately propagated to the -backend, but kept locally until g_settings_apply() is called. - - - - - - - a #GSettings object - - - - - - Gets the value that is stored at @key in @settings. - -A convenience function that combines g_settings_get_value() with -g_variant_get(). - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or for the #GVariantType of @format to mismatch -the type given in the schema. - - - - - - - a #GSettings object - - - - the key to get the value for - - - - a #GVariant format string - - - - arguments as per @format - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for booleans. - -It is a programmer error to give a @key that isn't specified as -having a boolean type in the schema for @settings. - - - a boolean - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Creates a child settings object which has a base path of -`base-path/@name`, where `base-path` is the base path of -@settings. - -The schema for the child settings object must have been declared -in the schema of @settings using a <child> element. - - - a 'child' settings object - - - - - a #GSettings object - - - - the name of the child schema - - - - - - Gets the "default value" of a key. - -This is the value that would be read if g_settings_reset() were to be -called on the key. - -Note that this may be a different value than returned by -g_settings_schema_key_get_default_value() if the system administrator -has provided a default value. - -Comparing the return values of g_settings_get_default_value() and -g_settings_get_value() is not sufficient for determining if a value -has been set because the user may have explicitly set the value to -something that happens to be equal to the default. The difference -here is that if the default changes in the future, the user's key -will still be set. - -This function may be useful for adding an indication to a UI of what -the default value was before the user set it. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings. - - - the default value - - - - - a #GSettings object - - - - the key to get the default value for - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for doubles. - -It is a programmer error to give a @key that isn't specified as -having a 'double' type in the schema for @settings. - - - a double - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored in @settings for @key and converts it -to the enum value that it represents. - -In order to use this function the type of the value must be a string -and it must be marked in the schema file as an enumerated type. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or is not marked as an enumerated type. - -If the value stored in the configuration database is not a valid -value for the enumerated type then this function will return the -default value. - - - the enum value - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored in @settings for @key and converts it -to the flags value that it represents. - -In order to use this function the type of the value must be an array -of strings and it must be marked in the schema file as a flags type. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or is not marked as a flags type. - -If the value stored in the configuration database is not a valid -value for the flags type then this function will return the default -value. - - - the flags value - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Returns whether the #GSettings object has any unapplied -changes. This can only be the case if it is in 'delayed-apply' mode. - - - %TRUE if @settings has unapplied changes - - - - - a #GSettings object - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for 32-bit integers. - -It is a programmer error to give a @key that isn't specified as -having a int32 type in the schema for @settings. - - - an integer - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for 64-bit integers. - -It is a programmer error to give a @key that isn't specified as -having a int64 type in the schema for @settings. - - - a 64-bit integer - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored at @key in @settings, subject to -application-level validation/mapping. - -You should use this function when the application needs to perform -some processing on the value of the key (for example, parsing). The -@mapping function performs that processing. If the function -indicates that the processing was unsuccessful (due to a parse error, -for example) then the mapping is tried again with another value. - -This allows a robust 'fall back to defaults' behaviour to be -implemented somewhat automatically. - -The first value that is tried is the user's setting for the key. If -the mapping function fails to map this value, other values may be -tried in an unspecified order (system or site defaults, translated -schema default values, untranslated schema default values, etc). - -If the mapping function fails for all possible values, one additional -attempt is made: the mapping function is called with a %NULL value. -If the mapping function still indicates failure at this point then -the application will be aborted. - -The result parameter for the @mapping function is pointed to a -#gpointer which is initially set to %NULL. The same pointer is given -to each invocation of @mapping. The final value of that #gpointer is -what is returned by this function. %NULL is valid; it is returned -just as any other value would be. - - - the result, which may be %NULL - - - - - a #GSettings object - - - - the key to get the value for - - - - the function to map the value in the - settings database to the value used by the application - - - - user data for @mapping - - - - - - Queries the range of a key. - Use g_settings_schema_key_get_range() instead. - - - - - - - a #GSettings - - - - the key to query the range of - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for strings. - -It is a programmer error to give a @key that isn't specified as -having a string type in the schema for @settings. - - - a newly-allocated string - - - - - a #GSettings object - - - - the key to get the value for - - - - - - A convenience variant of g_settings_get() for string arrays. - -It is a programmer error to give a @key that isn't specified as -having an array of strings type in the schema for @settings. - - - a -newly-allocated, %NULL-terminated array of strings, the value that -is stored at @key in @settings. - - - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for 32-bit unsigned -integers. - -It is a programmer error to give a @key that isn't specified as -having a uint32 type in the schema for @settings. - - - an unsigned integer - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Gets the value that is stored at @key in @settings. - -A convenience variant of g_settings_get() for 64-bit unsigned -integers. - -It is a programmer error to give a @key that isn't specified as -having a uint64 type in the schema for @settings. - - - a 64-bit unsigned integer - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Checks the "user value" of a key, if there is one. - -The user value of a key is the last value that was set by the user. - -After calling g_settings_reset() this function should always return -%NULL (assuming something is not wrong with the system -configuration). - -It is possible that g_settings_get_value() will return a different -value than this function. This can happen in the case that the user -set a value for a key that was subsequently locked down by the system -administrator -- this function will return the user's old value. - -This function may be useful for adding a "reset" option to a UI or -for providing indication that a particular value has been changed. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings. - - - the user's value, if set - - - - - a #GSettings object - - - - the key to get the user value for - - - - - - Gets the value that is stored in @settings for @key. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings. - - - a new #GVariant - - - - - a #GSettings object - - - - the key to get the value for - - - - - - Finds out if a key can be written or not - - - %TRUE if the key @name is writable - - - - - a #GSettings object - - - - the name of a key - - - - - - Gets the list of children on @settings. - -The list is exactly the list of strings for which it is not an error -to call g_settings_get_child(). - -There is little reason to call this function from "normal" code, since -you should already know what children are in your schema. This function -may still be useful there for introspection reasons, however. - -You should free the return value with g_strfreev() when you are done -with it. - - - a list of the children on - @settings, in no defined order - - - - - - - a #GSettings object - - - - - - Introspects the list of keys on @settings. - -You should probably not be calling this function from "normal" code -(since you should already know what keys are in your schema). This -function is intended for introspection reasons. - -You should free the return value with g_strfreev() when you are done -with it. - Use g_settings_schema_list_keys() instead. - - - a list of the keys on - @settings, in no defined order - - - - - - - a #GSettings object - - - - - - Checks if the given @value is of the correct type and within the -permitted range for @key. - Use g_settings_schema_key_range_check() instead. - - - %TRUE if @value is valid for @key - - - - - a #GSettings - - - - the key to check - - - - the value to check - - - - - - Resets @key to its default value. - -This call resets the key, as much as possible, to its default value. -That might be the value specified in the schema or the one set by the -administrator. - - - - - - - a #GSettings object - - - - the name of a key - - - - - - Reverts all non-applied changes to the settings. This function -does nothing unless @settings is in 'delay-apply' mode; see -g_settings_delay(). In the normal case settings are always applied -immediately. - -Change notifications will be emitted for affected keys. - - - - - - - a #GSettings instance - - - - - - Sets @key in @settings to @value. - -A convenience function that combines g_settings_set_value() with -g_variant_new(). - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or for the #GVariantType of @format to mismatch -the type given in the schema. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - a #GVariant format string - - - - arguments as per @format - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for booleans. - -It is a programmer error to give a @key that isn't specified as -having a boolean type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for doubles. - -It is a programmer error to give a @key that isn't specified as -having a 'double' type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Looks up the enumerated type nick for @value and writes it to @key, -within @settings. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or is not marked as an enumerated type, or for -@value not to be a valid value for the named type. - -After performing the write, accessing @key directly with -g_settings_get_string() will return the 'nick' associated with -@value. - - - %TRUE, if the set succeeds - - - - - a #GSettings object - - - - a key, within @settings - - - - an enumerated value - - - - - - Looks up the flags type nicks for the bits specified by @value, puts -them in an array of strings and writes the array to @key, within -@settings. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or is not marked as a flags type, or for @value -to contain any bits that are not value for the named type. - -After performing the write, accessing @key directly with -g_settings_get_strv() will return an array of 'nicks'; one for each -bit in @value. - - - %TRUE, if the set succeeds - - - - - a #GSettings object - - - - a key, within @settings - - - - a flags value - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for 32-bit integers. - -It is a programmer error to give a @key that isn't specified as -having a int32 type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for 64-bit integers. - -It is a programmer error to give a @key that isn't specified as -having a int64 type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for strings. - -It is a programmer error to give a @key that isn't specified as -having a string type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for string arrays. If -@value is %NULL, then @key is set to be the empty array. - -It is a programmer error to give a @key that isn't specified as -having an array of strings type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to, or %NULL - - - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for 32-bit unsigned -integers. - -It is a programmer error to give a @key that isn't specified as -having a uint32 type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -A convenience variant of g_settings_set() for 64-bit unsigned -integers. - -It is a programmer error to give a @key that isn't specified as -having a uint64 type in the schema for @settings. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - the value to set it to - - - - - - Sets @key in @settings to @value. - -It is a programmer error to give a @key that isn't contained in the -schema for @settings or for @value to have the incorrect type, per -the schema. - -If @value is floating then this function consumes the reference. - - - %TRUE if setting the key succeeded, - %FALSE if the key was not writable - - - - - a #GSettings object - - - - the name of the key to set - - - - a #GVariant of the correct type - - - - - - The name of the context that the settings are stored in. - - - - Whether the #GSettings object is in 'delay-apply' mode. See -g_settings_delay() for details. - - - - If this property is %TRUE, the #GSettings object has outstanding -changes that will be applied when g_settings_apply() is called. - - - - The path within the backend where the settings are stored. - - - - The name of the schema that describes the types of keys -for this #GSettings object. - -The type of this property is *not* #GSettingsSchema. -#GSettingsSchema has only existed since version 2.32 and -unfortunately this name was used in previous versions to refer to -the schema ID rather than the schema itself. Take care to use the -'settings-schema' property if you wish to pass in a -#GSettingsSchema. - Use the 'schema-id' property instead. In a future -version, this property may instead refer to a #GSettingsSchema. - - - - The name of the schema that describes the types of keys -for this #GSettings object. - - - - The #GSettingsSchema describing the types of keys for this -#GSettings object. - -Ideally, this property would be called 'schema'. #GSettingsSchema -has only existed since version 2.32, however, and before then the -'schema' property was used to refer to the ID of the schema rather -than the schema itself. Take care. - - - - - - - - - - The "change-event" signal is emitted once per change event that -affects this settings object. You should connect to this signal -only if you are interested in viewing groups of changes before they -are split out into multiple emissions of the "changed" signal. -For most use cases it is more appropriate to use the "changed" signal. - -In the event that the change event applies to one or more specified -keys, @keys will be an array of #GQuark of length @n_keys. In the -event that the change event applies to the #GSettings object as a -whole (ie: potentially every key has been changed) then @keys will -be %NULL and @n_keys will be 0. - -The default handler for this signal invokes the "changed" signal -for each affected key. If any other connected handler returns -%TRUE then this default functionality will be suppressed. - - %TRUE to stop other handlers from being invoked for the - event. FALSE to propagate the event further. - - - - - - an array of #GQuarks for the changed keys, or %NULL - - - - - - the length of the @keys array, or 0 - - - - - - The "changed" signal is emitted when a key has potentially changed. -You should call one of the g_settings_get() calls to check the new -value. - -This signal supports detailed connections. You can connect to the -detailed signal "changed::x" in order to only receive callbacks -when key "x" changes. - -Note that @settings only emits this signal if you have read @key at -least once while a signal handler was already connected for @key. - - - - - - the name of the key that changed - - - - - - The "writable-change-event" signal is emitted once per writability -change event that affects this settings object. You should connect -to this signal if you are interested in viewing groups of changes -before they are split out into multiple emissions of the -"writable-changed" signal. For most use cases it is more -appropriate to use the "writable-changed" signal. - -In the event that the writability change applies only to a single -key, @key will be set to the #GQuark for that key. In the event -that the writability change affects the entire settings object, -@key will be 0. - -The default handler for this signal invokes the "writable-changed" -and "changed" signals for each affected key. This is done because -changes in writability might also imply changes in value (if for -example, a new mandatory setting is introduced). If any other -connected handler returns %TRUE then this default functionality -will be suppressed. - - %TRUE to stop other handlers from being invoked for the - event. FALSE to propagate the event further. - - - - - the quark of the key, or 0 - - - - - - The "writable-changed" signal is emitted when the writability of a -key has potentially changed. You should call -g_settings_is_writable() in order to determine the new status. - -This signal supports detailed connections. You can connect to the -detailed signal "writable-changed::x" in order to only receive -callbacks when the writability of "x" changes. - - - - - - the key - - - - - - - The #GSettingsBackend interface defines a generic interface for -non-strictly-typed data that is stored in a hierarchy. To implement -an alternative storage backend for #GSettings, you need to implement -the #GSettingsBackend interface and then make it implement the -extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. - -The interface defines methods for reading and writing values, a -method for determining if writing of certain values will fail -(lockdown) and a change notification mechanism. - -The semantics of the interface are very precisely defined and -implementations must carefully adhere to the expectations of -callers that are documented on each of the interface methods. - -Some of the #GSettingsBackend functions accept or return a #GTree. -These trees always have strings as keys and #GVariant as values. -g_settings_backend_create_tree() is a convenience function to create -suitable trees. - -The #GSettingsBackend API is exported to allow third-party -implementations, but does not carry the same stability guarantees -as the public GIO API. For this reason, you have to define the -C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including -`gio/gsettingsbackend.h`. - - - Calculate the longest common prefix of all keys in a tree and write -out an array of the key names relative to that prefix and, -optionally, the value to store at each of those keys. - -You must free the value returned in @path, @keys and @values using -g_free(). You should not attempt to free or unref the contents of -@keys or @values. - - - - - - - a #GTree containing the changes - - - - the location to save the path - - - - the - location to save the relative keys - - - - - - - the location to save the values, or %NULL - - - - - - - - Returns the default #GSettingsBackend. It is possible to override -the default by setting the `GSETTINGS_BACKEND` environment variable -to the name of a settings backend. - -The user gets a reference to the backend. - - - the default #GSettingsBackend - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Signals that a single key has possibly changed. Backend -implementations should call this if a key has possibly changed its -value. - -@key must be a valid key (ie starting with a slash, not containing -'//', and not ending with a slash). - -The implementation must call this function during any call to -g_settings_backend_write(), before the call returns (except in the -case that no keys are actually changed and it cares to detect this -fact). It may not rely on the existence of a mainloop for -dispatching the signal later. - -The implementation may call this function at any other time it likes -in response to other events (such as changes occurring outside of the -program). These calls may originate from a mainloop or may originate -in response to any other action (including from calls to -g_settings_backend_write()). - -In the case that this call is in response to a call to -g_settings_backend_write() then @origin_tag must be set to the same -value that was passed to that call. - - - - - - - a #GSettingsBackend implementation - - - - the name of the key - - - - the origin tag - - - - - - This call is a convenience wrapper. It gets the list of changes from -@tree, computes the longest common prefix and calls -g_settings_backend_changed(). - - - - - - - a #GSettingsBackend implementation - - - - a #GTree containing the changes - - - - the origin tag - - - - - - Signals that a list of keys have possibly changed. Backend -implementations should call this if keys have possibly changed their -values. - -@path must be a valid path (ie starting and ending with a slash and -not containing '//'). Each string in @items must form a valid key -name when @path is prefixed to it (ie: each item must not start or -end with '/' and must not contain '//'). - -The meaning of this signal is that any of the key names resulting -from the contatenation of @path with each item in @items may have -changed. - -The same rules for when notifications must occur apply as per -g_settings_backend_changed(). These two calls can be used -interchangeably if exactly one item has changed (although in that -case g_settings_backend_changed() is definitely preferred). - -For efficiency reasons, the implementation should strive for @path to -be as long as possible (ie: the longest common prefix of all of the -keys that were changed) but this is not strictly required. - - - - - - - a #GSettingsBackend implementation - - - - the path containing the changes - - - - the %NULL-terminated list of changed keys - - - - - - the origin tag - - - - - - Signals that all keys below a given path may have possibly changed. -Backend implementations should call this if an entire path of keys -have possibly changed their values. - -@path must be a valid path (ie starting and ending with a slash and -not containing '//'). - -The meaning of this signal is that any of the key which has a name -starting with @path may have changed. - -The same rules for when notifications must occur apply as per -g_settings_backend_changed(). This call might be an appropriate -reasponse to a 'reset' call but implementations are also free to -explicitly list the keys that were affected by that call if they can -easily do so. - -For efficiency reasons, the implementation should strive for @path to -be as long as possible (ie: the longest common prefix of all of the -keys that were changed) but this is not strictly required. As an -example, if this function is called with the path of "/" then every -single key in the application will be notified of a possible change. - - - - - - - a #GSettingsBackend implementation - - - - the path containing the changes - - - - the origin tag - - - - - - Signals that the writability of all keys below a given path may have -changed. - -Since GSettings performs no locking operations for itself, this call -will always be made in response to external events. - - - - - - - a #GSettingsBackend implementation - - - - the name of the path - - - - - - Signals that the writability of a single key has possibly changed. - -Since GSettings performs no locking operations for itself, this call -will always be made in response to external events. - - - - - - - a #GSettingsBackend implementation - - - - the name of the key - - - - - - - - - - - - - Class structure for #GSettingsBackend. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flags used when creating a binding. These flags determine in which -direction the binding works. The default is to synchronize in both -directions. - - Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` - - - Update the #GObject property when the setting changes. - It is an error to use this flag if the property is not writable. - - - Update the setting when the #GObject property changes. - It is an error to use this flag if the property is not readable. - - - Do not try to bind a "sensitivity" property to the writability of the setting - - - When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property - value initially from the setting, but do not listen for changes of the setting - - - When passed to g_settings_bind(), uses a pair of mapping functions that invert - the boolean value when mapping between the setting and the property. The setting and property must both - be booleans. You cannot pass this flag to g_settings_bind_with_mapping(). - - - - The type for the function that is used to convert from #GSettings to -an object property. The @value is already initialized to hold values -of the appropriate type. - - - %TRUE if the conversion succeeded, %FALSE in case of an error - - - - - return location for the property value - - - - the #GVariant - - - - user data that was specified when the binding was created - - - - - - The type for the function that is used to convert an object property -value to a #GVariant for storing it in #GSettings. - - - a new #GVariant holding the data from @value, - or %NULL in case of an error - - - - - a #GValue containing the property value to map - - - - the #GVariantType to create - - - - user data that was specified when the binding was created - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of the function that is used to convert from a value stored -in a #GSettings to a value that is useful to the application. - -If the value is successfully mapped, the result should be stored at -@result and %TRUE returned. If mapping fails (for example, if @value -is not in the right format) then %FALSE should be returned. - -If @value is %NULL then it means that the mapping function is being -given a "last chance" to successfully return a valid value. %TRUE -must be returned in this case. - - - %TRUE if the conversion succeeded, %FALSE in case of an error - - - - - the #GVariant to map, or %NULL - - - - the result of the mapping - - - - the user data that was passed to -g_settings_get_mapped() - - - - - - - - - The #GSettingsSchemaSource and #GSettingsSchema APIs provide a -mechanism for advanced control over the loading of schemas and a -mechanism for introspecting their content. - -Plugin loading systems that wish to provide plugins a way to access -settings face the problem of how to make the schemas for these -settings visible to GSettings. Typically, a plugin will want to ship -the schema along with itself and it won't be installed into the -standard system directories for schemas. - -#GSettingsSchemaSource provides a mechanism for dealing with this by -allowing the creation of a new 'schema source' from which schemas can -be acquired. This schema source can then become part of the metadata -associated with the plugin and queried whenever the plugin requires -access to some settings. - -Consider the following example: - -|[<!-- language="C" --> -typedef struct -{ - ... - GSettingsSchemaSource *schema_source; - ... -} Plugin; - -Plugin * -initialise_plugin (const gchar *dir) -{ - Plugin *plugin; - - ... - - plugin->schema_source = - g_settings_schema_source_new_from_directory (dir, - g_settings_schema_source_get_default (), FALSE, NULL); - - ... - - return plugin; -} - -... - -GSettings * -plugin_get_settings (Plugin *plugin, - const gchar *schema_id) -{ - GSettingsSchema *schema; - - if (schema_id == NULL) - schema_id = plugin->identifier; - - schema = g_settings_schema_source_lookup (plugin->schema_source, - schema_id, FALSE); - - if (schema == NULL) - { - ... disable the plugin or abort, etc ... - } - - return g_settings_new_full (schema, NULL, NULL); -} -]| - -The code above shows how hooks should be added to the code that -initialises (or enables) the plugin to create the schema source and -how an API can be added to the plugin system to provide a convenient -way for the plugin to access its settings, using the schemas that it -ships. - -From the standpoint of the plugin, it would need to ensure that it -ships a gschemas.compiled file as part of itself, and then simply do -the following: - -|[<!-- language="C" --> -{ - GSettings *settings; - gint some_value; - - settings = plugin_get_settings (self, NULL); - some_value = g_settings_get_int (settings, "some-value"); - ... -} -]| - -It's also possible that the plugin system expects the schema source -files (ie: .gschema.xml files) instead of a gschemas.compiled file. -In that case, the plugin loading system must compile the schemas for -itself before attempting to create the settings source. - - - Get the ID of @schema. - - - the ID - - - - - a #GSettingsSchema - - - - - - Gets the key named @name from @schema. - -It is a programmer error to request a key that does not exist. See -g_settings_schema_list_keys(). - - - the #GSettingsSchemaKey for @name - - - - - a #GSettingsSchema - - - - the name of a key - - - - - - Gets the path associated with @schema, or %NULL. - -Schemas may be single-instance or relocatable. Single-instance -schemas correspond to exactly one set of keys in the backend -database: those located at the path returned by this function. - -Relocatable schemas can be referenced by other schemas and can -therefore describe multiple sets of keys at different locations. For -relocatable schemas, this function will return %NULL. - - - the path of the schema, or %NULL - - - - - a #GSettingsSchema - - - - - - Checks if @schema has a key named @name. - - - %TRUE if such a key exists - - - - - a #GSettingsSchema - - - - the name of a key - - - - - - Gets the list of children in @schema. - -You should free the return value with g_strfreev() when you are done -with it. - - - a list of the children on - @settings, in no defined order - - - - - - - a #GSettingsSchema - - - - - - Introspects the list of keys on @schema. - -You should probably not be calling this function from "normal" code -(since you should already know what keys are in your schema). This -function is intended for introspection reasons. - - - a list of the keys on - @schema, in no defined order - - - - - - - a #GSettingsSchema - - - - - - Increase the reference count of @schema, returning a new reference. - - - a new reference to @schema - - - - - a #GSettingsSchema - - - - - - Decrease the reference count of @schema, possibly freeing it. - - - - - - - a #GSettingsSchema - - - - - - - #GSettingsSchemaKey is an opaque data structure and can only be accessed -using the following functions. - - - Gets the default value for @key. - -Note that this is the default value according to the schema. System -administrator defaults and lockdown are not visible via this API. - - - the default value for the key - - - - - a #GSettingsSchemaKey - - - - - - Gets the description for @key. - -If no description has been provided in the schema for @key, returns -%NULL. - -The description can be one sentence to several paragraphs in length. -Paragraphs are delimited with a double newline. Descriptions can be -translated and the value returned from this function is is the -current locale. - -This function is slow. The summary and description information for -the schemas is not stored in the compiled schema database so this -function has to parse all of the source XML files in the schema -directory. - - - the description for @key, or %NULL - - - - - a #GSettingsSchemaKey - - - - - - Gets the name of @key. - - - the name of @key. - - - - - a #GSettingsSchemaKey - - - - - - Queries the range of a key. - -This function will return a #GVariant that fully describes the range -of values that are valid for @key. - -The type of #GVariant returned is `(sv)`. The string describes -the type of range restriction in effect. The type and meaning of -the value contained in the variant depends on the string. - -If the string is `'type'` then the variant contains an empty array. -The element type of that empty array is the expected type of value -and all values of that type are valid. - -If the string is `'enum'` then the variant contains an array -enumerating the possible values. Each item in the array is -a possible valid value and no other values are valid. - -If the string is `'flags'` then the variant contains an array. Each -item in the array is a value that may appear zero or one times in an -array to be used as the value for this key. For example, if the -variant contained the array `['x', 'y']` then the valid values for -the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and -`['y', 'x']`. - -Finally, if the string is `'range'` then the variant contains a pair -of like-typed values -- the minimum and maximum permissible values -for this key. - -This information should not be used by normal programs. It is -considered to be a hint for introspection purposes. Normal programs -should already know what is permitted by their own schema. The -format may change in any way in the future -- but particularly, new -forms may be added to the possibilities described above. - -You should free the returned value with g_variant_unref() when it is -no longer needed. - - - a #GVariant describing the range - - - - - a #GSettingsSchemaKey - - - - - - Gets the summary for @key. - -If no summary has been provided in the schema for @key, returns -%NULL. - -The summary is a short description of the purpose of the key; usually -one short sentence. Summaries can be translated and the value -returned from this function is is the current locale. - -This function is slow. The summary and description information for -the schemas is not stored in the compiled schema database so this -function has to parse all of the source XML files in the schema -directory. - - - the summary for @key, or %NULL - - - - - a #GSettingsSchemaKey - - - - - - Gets the #GVariantType of @key. - - - the type of @key - - - - - a #GSettingsSchemaKey - - - - - - Checks if the given @value is of the correct type and within the -permitted range for @key. - -It is a programmer error if @value is not of the correct type -- you -must check for this first. - - - %TRUE if @value is valid for @key - - - - - a #GSettingsSchemaKey - - - - the value to check - - - - - - Increase the reference count of @key, returning a new reference. - - - a new reference to @key - - - - - a #GSettingsSchemaKey - - - - - - Decrease the reference count of @key, possibly freeing it. - - - - - - - a #GSettingsSchemaKey - - - - - - - This is an opaque structure type. You may not access it directly. - - - Attempts to create a new schema source corresponding to the contents -of the given directory. - -This function is not required for normal uses of #GSettings but it -may be useful to authors of plugin management systems. - -The directory should contain a file called `gschemas.compiled` as -produced by the [glib-compile-schemas][glib-compile-schemas] tool. - -If @trusted is %TRUE then `gschemas.compiled` is trusted not to be -corrupted. This assumption has a performance advantage, but can result -in crashes or inconsistent behaviour in the case of a corrupted file. -Generally, you should set @trusted to %TRUE for files installed by the -system and to %FALSE for files in the home directory. - -In either case, an empty file or some types of corruption in the file will -result in %G_FILE_ERROR_INVAL being returned. - -If @parent is non-%NULL then there are two effects. - -First, if g_settings_schema_source_lookup() is called with the -@recursive flag set to %TRUE and the schema can not be found in the -source, the lookup will recurse to the parent. - -Second, any references to other schemas specified within this -source (ie: `child` or `extends`) references may be resolved -from the @parent. - -For this second reason, except in very unusual situations, the -@parent should probably be given as the default schema source, as -returned by g_settings_schema_source_get_default(). - - - - - - - the filename of a directory - - - - a #GSettingsSchemaSource, or %NULL - - - - %TRUE, if the directory is trusted - - - - - - Lists the schemas in a given source. - -If @recursive is %TRUE then include parent sources. If %FALSE then -only include the schemas from one source (ie: one directory). You -probably want %TRUE. - -Non-relocatable schemas are those for which you can call -g_settings_new(). Relocatable schemas are those for which you must -use g_settings_new_with_path(). - -Do not call this function from normal programs. This is designed for -use by database editors, commandline tools, etc. - - - - - - - a #GSettingsSchemaSource - - - - if we should recurse - - - - the - list of non-relocatable schemas, in no defined order - - - - - - the list - of relocatable schemas, in no defined order - - - - - - - - Looks up a schema with the identifier @schema_id in @source. - -This function is not required for normal uses of #GSettings but it -may be useful to authors of plugin management systems or to those who -want to introspect the content of schemas. - -If the schema isn't found directly in @source and @recursive is %TRUE -then the parent sources will also be checked. - -If the schema isn't found, %NULL is returned. - - - a new #GSettingsSchema - - - - - a #GSettingsSchemaSource - - - - a schema ID - - - - %TRUE if the lookup should be recursive - - - - - - Increase the reference count of @source, returning a new reference. - - - a new reference to @source - - - - - a #GSettingsSchemaSource - - - - - - Decrease the reference count of @source, possibly freeing it. - - - - - - - a #GSettingsSchemaSource - - - - - - Gets the default system schema source. - -This function is not required for normal uses of #GSettings but it -may be useful to authors of plugin management systems or to those who -want to introspect the content of schemas. - -If no schemas are installed, %NULL will be returned. - -The returned source may actually consist of multiple schema sources -from different directories, depending on which directories were given -in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all -lookups performed against the default source should probably be done -recursively. - - - the default schema source - - - - - - A #GSimpleAction is the obvious simple implementation of the #GAction -interface. This is the easiest way to create an action for purposes of -adding it to a #GSimpleActionGroup. - -See also #GtkAction. - - - Creates a new action. - -The created action is stateless. See g_simple_action_new_stateful() to create -an action that has state. - - - a new #GSimpleAction - - - - - the name of the action - - - - the type of parameter that will be passed to - handlers for the #GSimpleAction::activate signal, or %NULL for no parameter - - - - - - Creates a new stateful action. - -All future state values must have the same #GVariantType as the initial -@state. - -If the @state #GVariant is floating, it is consumed. - - - a new #GSimpleAction - - - - - the name of the action - - - - the type of the parameter that will be passed to - handlers for the #GSimpleAction::activate signal, or %NULL for no parameter - - - - the initial state of the action - - - - - - Sets the action as enabled or not. - -An action must be enabled in order to be activated or in order to -have its state changed from outside callers. - -This should only be called by the implementor of the action. Users -of the action should not attempt to modify its enabled flag. - - - - - - - a #GSimpleAction - - - - whether the action is enabled - - - - - - Sets the state of the action. - -This directly updates the 'state' property to the given value. - -This should only be called by the implementor of the action. Users -of the action should not attempt to directly modify the 'state' -property. Instead, they should call g_action_change_state() to -request the change. - -If the @value GVariant is floating, it is consumed. - - - - - - - a #GSimpleAction - - - - the new #GVariant for the state - - - - - - Sets the state hint for the action. - -See g_action_get_state_hint() for more information about -action state hints. - - - - - - - a #GSimpleAction - - - - a #GVariant representing the state hint - - - - - - If @action is currently enabled. - -If the action is disabled then calls to g_action_activate() and -g_action_change_state() have no effect. - - - - The name of the action. This is mostly meaningful for identifying -the action once it has been added to a #GSimpleActionGroup. - - - - The type of the parameter that must be given when activating the -action. - - - - The state of the action, or %NULL if the action is stateless. - - - - The #GVariantType of the state that the action has, or %NULL if the -action is stateless. - - - - Indicates that the action was just activated. - -@parameter will always be of the expected type, i.e. the parameter type -specified when the action was created. If an incorrect type is given when -activating the action, this signal is not emitted. - -Since GLib 2.40, if no handler is connected to this signal then the -default behaviour for boolean-stated actions with a %NULL parameter -type is to toggle them via the #GSimpleAction::change-state signal. -For stateful actions where the state type is equal to the parameter -type, the default is to forward them directly to -#GSimpleAction::change-state. This should allow almost all users -of #GSimpleAction to connect only one handler or the other. - - - - - - the parameter to the activation, or %NULL if it has - no parameter - - - - - - Indicates that the action just received a request to change its -state. - -@value will always be of the correct state type, i.e. the type of the -initial state passed to g_simple_action_new_stateful(). If an incorrect -type is given when requesting to change the state, this signal is not -emitted. - -If no handler is connected to this signal then the default -behaviour is to call g_simple_action_set_state() to set the state -to the requested value. If you connect a signal handler then no -default action is taken. If the state should change then you must -call g_simple_action_set_state() from the handler. - -An example of a 'change-state' handler: -|[<!-- language="C" --> -static void -change_volume_state (GSimpleAction *action, - GVariant *value, - gpointer user_data) -{ - gint requested; - - requested = g_variant_get_int32 (value); - - // Volume only goes from 0 to 10 - if (0 <= requested && requested <= 10) - g_simple_action_set_state (action, value); -} -]| - -The handler need not set the state to the requested value. -It could set it to any value at all, or take some other action. - - - - - - the requested value for the state - - - - - - - #GSimpleActionGroup is a hash table filled with #GAction objects, -implementing the #GActionGroup and #GActionMap interfaces. - - - - - Creates a new, empty, #GSimpleActionGroup. - - - a new #GSimpleActionGroup - - - - - A convenience function for creating multiple #GSimpleAction instances -and adding them to the action group. - Use g_action_map_add_action_entries() - - - - - - - a #GSimpleActionGroup - - - - a pointer to the first item in - an array of #GActionEntry structs - - - - - - the length of @entries, or -1 - - - - the user data for signal connections - - - - - - Adds an action to the action group. - -If the action group already contains an action with the same name as -@action then the old action is dropped from the group. - -The action group takes its own reference on @action. - Use g_action_map_add_action() - - - - - - - a #GSimpleActionGroup - - - - a #GAction - - - - - - Looks up the action with the name @action_name in the group. - -If no such action exists, returns %NULL. - Use g_action_map_lookup_action() - - - a #GAction, or %NULL - - - - - a #GSimpleActionGroup - - - - the name of an action - - - - - - Removes the named action from the action group. - -If no action of this name is in the group then nothing happens. - Use g_action_map_remove_action() - - - - - - - a #GSimpleActionGroup - - - - the name of the action - - - - - - - - - - - - - - - - - - - - - - - - - - - As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of -#GTask, which provides a simpler API. - -#GSimpleAsyncResult implements #GAsyncResult. - -GSimpleAsyncResult handles #GAsyncReadyCallbacks, error -reporting, operation cancellation and the final state of an operation, -completely transparent to the application. Results can be returned -as a pointer e.g. for functions that return data that is collected -asynchronously, a boolean value for checking the success or failure -of an operation, or a #gssize for operations which return the number -of bytes modified by the operation; all of the simple return cases -are covered. - -Most of the time, an application will not need to know of the details -of this API; it is handled transparently, and any necessary operations -are handled by #GAsyncResult's interface. However, if implementing a -new GIO module, for writing language bindings, or for complex -applications that need better control of how asynchronous operations -are completed, it is important to understand this functionality. - -GSimpleAsyncResults are tagged with the calling function to ensure -that asynchronous functions and their finishing functions are used -together correctly. - -To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). -If the result needs to be created for a #GError, use -g_simple_async_result_new_from_error() or -g_simple_async_result_new_take_error(). If a #GError is not available -(e.g. the asynchronous operation's doesn't take a #GError argument), -but the result still needs to be created for an error condition, use -g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() -if your application or binding requires passing a variable argument list -directly), and the error can then be propagated through the use of -g_simple_async_result_propagate_error(). - -An asynchronous operation can be made to ignore a cancellation event by -calling g_simple_async_result_set_handle_cancellation() with a -#GSimpleAsyncResult for the operation and %FALSE. This is useful for -operations that are dangerous to cancel, such as close (which would -cause a leak if cancelled before being run). - -GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, -or it can use #GThreads. -g_simple_async_result_complete() will finish an I/O task directly -from the point where it is called. g_simple_async_result_complete_in_idle() -will finish it from an idle handler in the -[thread-default main context][g-main-context-push-thread-default] -where the #GSimpleAsyncResult was created. -g_simple_async_result_run_in_thread() will run the job in a -separate thread and then use -g_simple_async_result_complete_in_idle() to deliver the result. - -To set the results of an asynchronous function, -g_simple_async_result_set_op_res_gpointer(), -g_simple_async_result_set_op_res_gboolean(), and -g_simple_async_result_set_op_res_gssize() -are provided, setting the operation's result to a gpointer, gboolean, or -gssize, respectively. - -Likewise, to get the result of an asynchronous function, -g_simple_async_result_get_op_res_gpointer(), -g_simple_async_result_get_op_res_gboolean(), and -g_simple_async_result_get_op_res_gssize() are -provided, getting the operation's result as a gpointer, gboolean, and -gssize, respectively. - -For the details of the requirements implementations must respect, see -#GAsyncResult. A typical implementation of an asynchronous operation -using GSimpleAsyncResult looks something like this: - -|[<!-- language="C" --> -static void -baked_cb (Cake *cake, - gpointer user_data) -{ - // In this example, this callback is not given a reference to the cake, - // so the GSimpleAsyncResult has to take a reference to it. - GSimpleAsyncResult *result = user_data; - - if (cake == NULL) - g_simple_async_result_set_error (result, - BAKER_ERRORS, - BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - else - g_simple_async_result_set_op_res_gpointer (result, - g_object_ref (cake), - g_object_unref); - - - // In this example, we assume that baked_cb is called as a callback from - // the mainloop, so it's safe to complete the operation synchronously here. - // If, however, _baker_prepare_cake () might call its callback without - // first returning to the mainloop — inadvisable, but some APIs do so — - // we would need to use g_simple_async_result_complete_in_idle(). - g_simple_async_result_complete (result); - g_object_unref (result); -} - -void -baker_bake_cake_async (Baker *self, - guint radius, - GAsyncReadyCallback callback, - gpointer user_data) -{ - GSimpleAsyncResult *simple; - Cake *cake; - - if (radius < 3) - { - g_simple_async_report_error_in_idle (G_OBJECT (self), - callback, - user_data, - BAKER_ERRORS, - BAKER_ERROR_TOO_SMALL, - "%ucm radius cakes are silly", - radius); - return; - } - - simple = g_simple_async_result_new (G_OBJECT (self), - callback, - user_data, - baker_bake_cake_async); - cake = _baker_get_cached_cake (self, radius); - - if (cake != NULL) - { - g_simple_async_result_set_op_res_gpointer (simple, - g_object_ref (cake), - g_object_unref); - g_simple_async_result_complete_in_idle (simple); - g_object_unref (simple); - // Drop the reference returned by _baker_get_cached_cake(); - // the GSimpleAsyncResult has taken its own reference. - g_object_unref (cake); - return; - } - - _baker_prepare_cake (self, radius, baked_cb, simple); -} - -Cake * -baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) -{ - GSimpleAsyncResult *simple; - Cake *cake; - - g_return_val_if_fail (g_simple_async_result_is_valid (result, - G_OBJECT (self), - baker_bake_cake_async), - NULL); - - simple = (GSimpleAsyncResult *) result; - - if (g_simple_async_result_propagate_error (simple, error)) - return NULL; - - cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); - return g_object_ref (cake); -} -]| - - - - Creates a #GSimpleAsyncResult. - -The common convention is to create the #GSimpleAsyncResult in the -function that starts the asynchronous operation and use that same -function as the @source_tag. - -If your operation supports cancellation with #GCancellable (which it -probably should) then you should provide the user's cancellable to -g_simple_async_result_set_check_cancellable() immediately after -this function returns. - Use g_task_new() instead. - - - a #GSimpleAsyncResult. - - - - - a #GObject, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - the asynchronous function. - - - - - - Creates a new #GSimpleAsyncResult with a set error. - Use g_task_new() and g_task_return_new_error() instead. - - - a #GSimpleAsyncResult. - - - - - a #GObject, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - a #GQuark. - - - - an error code. - - - - a string with format characters. - - - - a list of values to insert into @format. - - - - - - Creates a #GSimpleAsyncResult from an error condition. - Use g_task_new() and g_task_return_error() instead. - - - a #GSimpleAsyncResult. - - - - - a #GObject, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - a #GError - - - - - - Creates a #GSimpleAsyncResult from an error condition, and takes over the -caller's ownership of @error, so the caller does not need to free it anymore. - Use g_task_new() and g_task_return_error() instead. - - - a #GSimpleAsyncResult - - - - - a #GObject, or %NULL - - - - a #GAsyncReadyCallback - - - - user data passed to @callback - - - - a #GError - - - - - - Ensures that the data passed to the _finish function of an async -operation is consistent. Three checks are performed. - -First, @result is checked to ensure that it is really a -#GSimpleAsyncResult. Second, @source is checked to ensure that it -matches the source object of @result. Third, @source_tag is -checked to ensure that it is equal to the @source_tag argument given -to g_simple_async_result_new() (which, by convention, is a pointer -to the _async function corresponding to the _finish function from -which this function is called). (Alternatively, if either -@source_tag or @result's source tag is %NULL, then the source tag -check is skipped.) - Use #GTask and g_task_is_valid() instead. - - - #TRUE if all checks passed or #FALSE if any failed. - - - - - the #GAsyncResult passed to the _finish function. - - - - the #GObject passed to the _finish function. - - - - the asynchronous function. - - - - - - Completes an asynchronous I/O job immediately. Must be called in -the thread where the asynchronous result was to be delivered, as it -invokes the callback directly. If you are in a different thread use -g_simple_async_result_complete_in_idle(). - -Calling this function takes a reference to @simple for as long as -is needed to complete the call. - Use #GTask instead. - - - - - - - a #GSimpleAsyncResult. - - - - - - Completes an asynchronous function in an idle handler in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that @simple was initially created in -(and re-pushes that context around the invocation of the callback). - -Calling this function takes a reference to @simple for as long as -is needed to complete the call. - Use #GTask instead. - - - - - - - a #GSimpleAsyncResult. - - - - - - Gets the operation result boolean from within the asynchronous result. - Use #GTask and g_task_propagate_boolean() instead. - - - %TRUE if the operation's result was %TRUE, %FALSE - if the operation's result was %FALSE. - - - - - a #GSimpleAsyncResult. - - - - - - Gets a pointer result as returned by the asynchronous function. - Use #GTask and g_task_propagate_pointer() instead. - - - a pointer from the result. - - - - - a #GSimpleAsyncResult. - - - - - - Gets a gssize from the asynchronous result. - Use #GTask and g_task_propagate_int() instead. - - - a gssize returned from the asynchronous function. - - - - - a #GSimpleAsyncResult. - - - - - - Gets the source tag for the #GSimpleAsyncResult. - Use #GTask and g_task_get_source_tag() instead. - - - a #gpointer to the source object for the #GSimpleAsyncResult. - - - - - a #GSimpleAsyncResult. - - - - - - Propagates an error from within the simple asynchronous result to -a given destination. - -If the #GCancellable given to a prior call to -g_simple_async_result_set_check_cancellable() is cancelled then this -function will return %TRUE with @dest set appropriately. - Use #GTask instead. - - - %TRUE if the error was propagated to @dest. %FALSE otherwise. - - - - - a #GSimpleAsyncResult. - - - - - - Runs the asynchronous job in a separate thread and then calls -g_simple_async_result_complete_in_idle() on @simple to return -the result to the appropriate main loop. - -Calling this function takes a reference to @simple for as long as -is needed to run the job and report its completion. - Use #GTask and g_task_run_in_thread() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a #GSimpleAsyncThreadFunc. - - - - the io priority of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Sets a #GCancellable to check before dispatching results. - -This function has one very specific purpose: the provided cancellable -is checked at the time of g_simple_async_result_propagate_error() If -it is cancelled, these functions will return an "Operation was -cancelled" error (%G_IO_ERROR_CANCELLED). - -Implementors of cancellable asynchronous functions should use this in -order to provide a guarantee to their callers that cancelling an -async operation will reliably result in an error being returned for -that operation (even if a positive result for the operation has -already been sent as an idle to the main context to be dispatched). - -The checking described above is done regardless of any call to the -unrelated g_simple_async_result_set_handle_cancellation() function. - Use #GTask instead. - - - - - - - a #GSimpleAsyncResult - - - - a #GCancellable to check, or %NULL to unset - - - - - - Sets an error within the asynchronous result without a #GError. - Use #GTask and g_task_return_new_error() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a #GQuark (usually #G_IO_ERROR). - - - - an error code. - - - - a formatted error reporting string. - - - - a list of variables to fill in @format. - - - - - - Sets an error within the asynchronous result without a #GError. -Unless writing a binding, see g_simple_async_result_set_error(). - Use #GTask and g_task_return_error() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a #GQuark (usually #G_IO_ERROR). - - - - an error code. - - - - a formatted error reporting string. - - - - va_list of arguments. - - - - - - Sets the result from a #GError. - Use #GTask and g_task_return_error() instead. - - - - - - - a #GSimpleAsyncResult. - - - - #GError. - - - - - - Sets whether to handle cancellation within the asynchronous operation. - -This function has nothing to do with -g_simple_async_result_set_check_cancellable(). It only refers to the -#GCancellable passed to g_simple_async_result_run_in_thread(). - - - - - - - a #GSimpleAsyncResult. - - - - a #gboolean. - - - - - - Sets the operation result to a boolean within the asynchronous result. - Use #GTask and g_task_return_boolean() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a #gboolean. - - - - - - Sets the operation result within the asynchronous result to a pointer. - Use #GTask and g_task_return_pointer() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a pointer result from an asynchronous function. - - - - a #GDestroyNotify function. - - - - - - Sets the operation result within the asynchronous result to -the given @op_res. - Use #GTask and g_task_return_int() instead. - - - - - - - a #GSimpleAsyncResult. - - - - a #gssize. - - - - - - Sets the result from @error, and takes over the caller's ownership -of @error, so the caller does not need to free it any more. - Use #GTask and g_task_return_error() instead. - - - - - - - a #GSimpleAsyncResult - - - - a #GError - - - - - - - - - - Simple thread function that runs an asynchronous operation and -checks for cancellation. - - - - - - - a #GSimpleAsyncResult. - - - - a #GObject. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and -#GOutputStream. This allows any pair of input and output streams to be used -with #GIOStream methods. - -This is useful when you obtained a #GInputStream and a #GOutputStream -by other means, for instance creating them with platform specific methods as -g_unix_input_stream_new() or g_win32_input_stream_new(), and you want -to take advantage of the methods provided by #GIOStream. - - Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. -See also #GIOStream. - - - a new #GSimpleIOStream instance. - - - - - a #GInputStream. - - - - a #GOutputStream. - - - - - - - - - - - - - #GSimplePermission is a trivial implementation of #GPermission that -represents a permission that is either always or never allowed. The -value is given at construction and doesn't change. - -Calling request or release will result in errors. - - Creates a new #GPermission instance that represents an action that is -either always or never allowed. - - - the #GSimplePermission, as a #GPermission - - - - - %TRUE if the action is allowed - - - - - - - #GSimpleProxyResolver is a simple #GProxyResolver implementation -that handles a single default proxy, multiple URI-scheme-specific -proxies, and a list of hosts that proxies should not be used for. - -#GSimpleProxyResolver is never the default proxy resolver, but it -can be used as the base class for another proxy resolver -implementation, or it can be created and used manually, such as -with g_socket_client_set_proxy_resolver(). - - - - Creates a new #GSimpleProxyResolver. See -#GSimpleProxyResolver:default-proxy and -#GSimpleProxyResolver:ignore-hosts for more details on how the -arguments are interpreted. - - - a new #GSimpleProxyResolver - - - - - the default proxy to use, eg - "socks://192.168.1.1" - - - - an optional list of hosts/IP addresses - to not use a proxy for. - - - - - - Sets the default proxy on @resolver, to be used for any URIs that -don't match #GSimpleProxyResolver:ignore-hosts or a proxy set -via g_simple_proxy_resolver_set_uri_proxy(). - -If @default_proxy starts with "socks://", -#GSimpleProxyResolver will treat it as referring to all three of -the socks5, socks4a, and socks4 proxy types. - - - - - - - a #GSimpleProxyResolver - - - - the default proxy to use - - - - - - Sets the list of ignored hosts. - -See #GSimpleProxyResolver:ignore-hosts for more details on how the -@ignore_hosts argument is interpreted. - - - - - - - a #GSimpleProxyResolver - - - - %NULL-terminated list of hosts/IP addresses - to not use a proxy for - - - - - - Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme -matches @uri_scheme (and which don't match -#GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. - -As with #GSimpleProxyResolver:default-proxy, if @proxy starts with -"socks://", #GSimpleProxyResolver will treat it -as referring to all three of the socks5, socks4a, and socks4 proxy -types. - - - - - - - a #GSimpleProxyResolver - - - - the URI scheme to add a proxy for - - - - the proxy to use for @uri_scheme - - - - - - The default proxy URI that will be used for any URI that doesn't -match #GSimpleProxyResolver:ignore-hosts, and doesn't match any -of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). - -Note that as a special case, if this URI starts with -"socks://", #GSimpleProxyResolver will treat it as referring -to all three of the socks5, socks4a, and socks4 proxy types. - - - - A list of hostnames and IP addresses that the resolver should -allow direct connections to. - -Entries can be in one of 4 formats: - -- A hostname, such as "example.com", ".example.com", or - "*.example.com", any of which match "example.com" or - any subdomain of it. - -- An IPv4 or IPv6 address, such as "192.168.1.1", - which matches only that address. - -- A hostname or IP address followed by a port, such as - "example.com:80", which matches whatever the hostname or IP - address would match, but only for URLs with the (explicitly) - indicated port. In the case of an IPv6 address, the address - part must appear in brackets: "[::1]:443" - -- An IP address range, given by a base address and prefix length, - such as "fe80::/10", which matches any address in that range. - -Note that when dealing with Unicode hostnames, the matching is -done against the ASCII form of the name. - -Also note that hostname exclusions apply only to connections made -to hosts identified by name, and IP address exclusions apply only -to connections made to hosts identified by address. That is, if -example.com has an address of 192.168.1.1, and the :ignore-hosts list -contains only "192.168.1.1", then a connection to "example.com" -(eg, via a #GNetworkAddress) will use the proxy, and a connection to -"192.168.1.1" (eg, via a #GInetSocketAddress) will not. - -These rules match the "ignore-hosts"/"noproxy" rules most -commonly used by other applications. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GSocket is a low-level networking primitive. It is a more or less -direct mapping of the BSD socket API in a portable GObject based API. -It supports both the UNIX socket implementations and winsock2 on Windows. - -#GSocket is the platform independent base upon which the higher level -network primitives are based. Applications are not typically meant to -use it directly, but rather through classes like #GSocketClient, -#GSocketService and #GSocketConnection. However there may be cases where -direct use of #GSocket is useful. - -#GSocket implements the #GInitable interface, so if it is manually constructed -by e.g. g_object_new() you must call g_initable_init() and check the -results before using the object. This is done automatically in -g_socket_new() and g_socket_new_from_fd(), so these functions can return -%NULL. - -Sockets operate in two general modes, blocking or non-blocking. When -in blocking mode all operations (which don’t take an explicit blocking -parameter) block until the requested operation -is finished or there is an error. In non-blocking mode all calls that -would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. -To know when a call would successfully run you can call g_socket_condition_check(), -or g_socket_condition_wait(). You can also use g_socket_create_source() and -attach it to a #GMainContext to get callbacks when I/O is possible. -Note that all sockets are always set to non blocking mode in the system, and -blocking mode is emulated in GSocket. - -When working in non-blocking mode applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other -function said that I/O was possible. This can easily happen in case -of a race condition in the application, but it can also happen for other -reasons. For instance, on Windows a socket is always seen as writable -until a write returns %G_IO_ERROR_WOULD_BLOCK. - -#GSockets can be either connection oriented or datagram based. -For connection oriented types you must first establish a connection by -either connecting to an address or accepting a connection from another -address. For connectionless socket types the target/source address is -specified or received in each I/O operation. - -All socket file descriptors are set to be close-on-exec. - -Note that creating a #GSocket causes the signal %SIGPIPE to be -ignored for the remainder of the program. If you are writing a -command-line utility that uses #GSocket, you may need to take into -account the fact that your program will not automatically be killed -if it tries to write to %stdout after it has been closed. - -Like most other APIs in GLib, #GSocket is not inherently thread safe. To use -a #GSocket concurrently from multiple threads, you must implement your own -locking. - - - - - Creates a new #GSocket with the defined family, type and protocol. -If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type -for the family and type is used. - -The @protocol is a family and type specific int that specifies what -kind of protocol to use. #GSocketProtocol lists several common ones. -Many families only support one protocol, and use 0 for this, others -support several and using 0 means to use the default protocol for -the family and type. - -The protocol id is passed directly to the operating -system, so you can use protocols not listed in #GSocketProtocol if you -know the protocol number used for it. - - - a #GSocket or %NULL on error. - Free the returned object with g_object_unref(). - - - - - the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. - - - - the socket type to use. - - - - the id of the protocol to use, or 0 for default. - - - - - - Creates a new #GSocket from a native file descriptor -or winsock SOCKET handle. - -This reads all the settings from the file descriptor so that -all properties should work. Note that the file descriptor -will be set to non-blocking mode, independent on the blocking -mode of the #GSocket. - -On success, the returned #GSocket takes ownership of @fd. On failure, the -caller must close @fd themselves. - -Since GLib 2.46, it is no longer a fatal error to call this on a non-socket -descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED - - - a #GSocket or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a native socket file descriptor. - - - - - - Accept incoming connections on a connection-based socket. This removes -the first outstanding connection request from the listening socket and -creates a #GSocket object for it. - -The @socket must be bound to a local address with g_socket_bind() and -must be listening for incoming connections (g_socket_listen()). - -If there are no outstanding connections then the operation will block -or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. -To be notified of an incoming connection, wait for the %G_IO_IN condition. - - - a new #GSocket, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GSocket. - - - - a %GCancellable or %NULL - - - - - - When a socket is created it is attached to an address family, but it -doesn't have an address in this family. g_socket_bind() assigns the -address (sometimes called name) of the socket. - -It is generally required to bind to a local address before you can -receive connections. (See g_socket_listen() and g_socket_accept() ). -In certain situations, you may also want to bind a socket that will be -used to initiate connections, though this is not normally required. - -If @socket is a TCP socket, then @allow_reuse controls the setting -of the `SO_REUSEADDR` socket option; normally it should be %TRUE for -server sockets (sockets that you will eventually call -g_socket_accept() on), and %FALSE for client sockets. (Failing to -set this flag on a server socket may cause g_socket_bind() to return -%G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then -immediately restarted.) - -If @socket is a UDP socket, then @allow_reuse determines whether or -not other UDP sockets can be bound to the same address at the same -time. In particular, you can have several UDP sockets bound to the -same address, and they will all receive all of the multicast and -broadcast packets sent to that address. (The behavior of unicast -UDP packets to an address with multiple listeners is not defined.) - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - a #GSocketAddress specifying the local address. - - - - whether to allow reusing this address - - - - - - Checks and resets the pending connect error for the socket. -This is used to check for errors when g_socket_connect() is -used in non-blocking mode. - - - %TRUE if no error, %FALSE otherwise, setting @error to the error - - - - - a #GSocket - - - - - - Closes the socket, shutting down any active connection. - -Closing a socket does not wait for all outstanding I/O operations -to finish, so the caller should not rely on them to be guaranteed -to complete even if the close returns with no error. - -Once the socket is closed, all other operations will return -%G_IO_ERROR_CLOSED. Closing a socket multiple times will not -return an error. - -Sockets will be automatically closed when the last reference -is dropped, but you might want to call this function to make sure -resources are released as early as possible. - -Beware that due to the way that TCP works, it is possible for -recently-sent data to be lost if either you close a socket while the -%G_IO_IN condition is set, or else if the remote connection tries to -send something to you after you close the socket but before it has -finished reading all of the data you sent. There is no easy generic -way to avoid this problem; the easiest fix is to design the network -protocol such that the client will never send data "out of turn". -Another solution is for the server to half-close the connection by -calling g_socket_shutdown() with only the @shutdown_write flag set, -and then wait for the client to notice this and close its side of the -connection, after which the server can safely call g_socket_close(). -(This is what #GTcpConnection does if you call -g_tcp_connection_set_graceful_disconnect(). But of course, this -only works if the client will close its connection after the server -does.) - - - %TRUE on success, %FALSE on error - - - - - a #GSocket - - - - - - Checks on the readiness of @socket to perform operations. -The operations specified in @condition are checked for and masked -against the currently-satisfied conditions on @socket. The result -is returned. - -Note that on Windows, it is possible for an operation to return -%G_IO_ERROR_WOULD_BLOCK even immediately after -g_socket_condition_check() has claimed that the socket is ready for -writing. Rather than calling g_socket_condition_check() and then -writing to the socket if it succeeds, it is generally better to -simply try writing to the socket right away, and try again later if -the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; -these conditions will always be set in the output if they are true. - -This call never blocks. - - - the @GIOCondition mask of the current state - - - - - a #GSocket - - - - a #GIOCondition mask to check - - - - - - Waits for up to @timeout_us microseconds for @condition to become true -on @socket. If the condition is met, %TRUE is returned. - -If @cancellable is cancelled before the condition is met, or if -@timeout_us (or the socket's #GSocket:timeout) is reached before the -condition is met, then %FALSE is returned and @error, if non-%NULL, -is set to the appropriate value (%G_IO_ERROR_CANCELLED or -%G_IO_ERROR_TIMED_OUT). - -If you don't want a timeout, use g_socket_condition_wait(). -(Alternatively, you can pass -1 for @timeout_us.) - -Note that although @timeout_us is in microseconds for consistency with -other GLib APIs, this function actually only has millisecond -resolution, and the behavior is undefined if @timeout_us is not an -exact number of milliseconds. - - - %TRUE if the condition was met, %FALSE otherwise - - - - - a #GSocket - - - - a #GIOCondition mask to wait for - - - - the maximum time (in microseconds) to wait, or -1 - - - - a #GCancellable, or %NULL - - - - - - Waits for @condition to become true on @socket. When the condition -is met, %TRUE is returned. - -If @cancellable is cancelled before the condition is met, or if the -socket has a timeout set and it is reached before the condition is -met, then %FALSE is returned and @error, if non-%NULL, is set to -the appropriate value (%G_IO_ERROR_CANCELLED or -%G_IO_ERROR_TIMED_OUT). - -See also g_socket_condition_timed_wait(). - - - %TRUE if the condition was met, %FALSE otherwise - - - - - a #GSocket - - - - a #GIOCondition mask to wait for - - - - a #GCancellable, or %NULL - - - - - - Connect the socket to the specified remote address. - -For connection oriented socket this generally means we attempt to make -a connection to the @address. For a connection-less socket it sets -the default address for g_socket_send() and discards all incoming datagrams -from other sources. - -Generally connection oriented sockets can only connect once, but -connection-less sockets can connect multiple times to change the -default address. - -If the connect call needs to do network I/O it will block, unless -non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned -and the user can be notified of the connection finishing by waiting -for the G_IO_OUT condition. The result of the connection must then be -checked with g_socket_check_connect_result(). - - - %TRUE if connected, %FALSE on error. - - - - - a #GSocket. - - - - a #GSocketAddress specifying the remote address. - - - - a %GCancellable or %NULL - - - - - - Creates a #GSocketConnection subclass of the right type for -@socket. - - - a #GSocketConnection - - - - - a #GSocket - - - - - - Creates a #GSource that can be attached to a %GMainContext to monitor -for the availability of the specified @condition on the socket. The #GSource -keeps a reference to the @socket. - -The callback on the source is of the #GSocketSourceFunc type. - -It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; -these conditions will always be reported output if they are true. - -@cancellable if not %NULL can be used to cancel the source, which will -cause the source to trigger, reporting the current condition (which -is likely 0 unless cancellation happened at the same time as a -condition change). You can check for this in the callback using -g_cancellable_is_cancelled(). - -If @socket has a timeout set, and it is reached before @condition -occurs, the source will then trigger anyway, reporting %G_IO_IN or -%G_IO_OUT depending on @condition. However, @socket will have been -marked as having had a timeout, and so the next #GSocket I/O method -you call will then fail with a %G_IO_ERROR_TIMED_OUT. - - - a newly allocated %GSource, free with g_source_unref(). - - - - - a #GSocket - - - - a #GIOCondition mask to monitor - - - - a %GCancellable or %NULL - - - - - - Get the amount of data pending in the OS input buffer, without blocking. - -If @socket is a UDP or SCTP socket, this will return the size of -just the next packet, even if additional packets are buffered after -that one. - -Note that on Windows, this function is rather inefficient in the -UDP case, and so if you know any plausible upper bound on the size -of the incoming packet, it is better to just do a -g_socket_receive() with a buffer of that size, rather than calling -g_socket_get_available_bytes() first and then doing a receive of -exactly the right size. - - - the number of bytes that can be read from the socket -without blocking or truncating, or -1 on error. - - - - - a #GSocket - - - - - - Gets the blocking mode of the socket. For details on blocking I/O, -see g_socket_set_blocking(). - - - %TRUE if blocking I/O is used, %FALSE otherwise. - - - - - a #GSocket. - - - - - - Gets the broadcast setting on @socket; if %TRUE, -it is possible to send packets to broadcast -addresses. - - - the broadcast setting on @socket - - - - - a #GSocket. - - - - - - Returns the credentials of the foreign process connected to this -socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX -sockets). - -If this operation isn't supported on the OS, the method fails with -the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented -by reading the %SO_PEERCRED option on the underlying socket. - -This method can be expected to be available on the following platforms: - -- Linux since GLib 2.26 -- OpenBSD since GLib 2.30 -- Solaris, Illumos and OpenSolaris since GLib 2.40 -- NetBSD since GLib 2.42 - -Other ways to obtain credentials from a foreign peer includes the -#GUnixCredentialsMessage type and -g_unix_connection_send_credentials() / -g_unix_connection_receive_credentials() functions. - - - %NULL if @error is set, otherwise a #GCredentials object -that must be freed with g_object_unref(). - - - - - a #GSocket. - - - - - - Gets the socket family of the socket. - - - a #GSocketFamily - - - - - a #GSocket. - - - - - - Returns the underlying OS socket object. On unix this -is a socket file descriptor, and on Windows this is -a Winsock2 SOCKET handle. This may be useful for -doing platform specific or otherwise unusual operations -on the socket. - - - the file descriptor of the socket. - - - - - a #GSocket. - - - - - - Gets the keepalive mode of the socket. For details on this, -see g_socket_set_keepalive(). - - - %TRUE if keepalive is active, %FALSE otherwise. - - - - - a #GSocket. - - - - - - Gets the listen backlog setting of the socket. For details on this, -see g_socket_set_listen_backlog(). - - - the maximum number of pending connections. - - - - - a #GSocket. - - - - - - Try to get the local address of a bound socket. This is only -useful if the socket has been bound to a local address, -either explicitly or implicitly when connecting. - - - a #GSocketAddress or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GSocket. - - - - - - Gets the multicast loopback setting on @socket; if %TRUE (the -default), outgoing multicast packets will be looped back to -multicast listeners on the same host. - - - the multicast loopback setting on @socket - - - - - a #GSocket. - - - - - - Gets the multicast time-to-live setting on @socket; see -g_socket_set_multicast_ttl() for more details. - - - the multicast time-to-live setting on @socket - - - - - a #GSocket. - - - - - - Gets the value of an integer-valued option on @socket, as with -getsockopt(). (If you need to fetch a non-integer-valued option, -you will need to call getsockopt() directly.) - -The [<gio/gnetworking.h>][gio-gnetworking.h] -header pulls in system headers that will define most of the -standard/portable socket options. For unusual socket protocols or -platform-dependent options, you may need to include additional -headers. - -Note that even for socket options that are a single byte in size, -@value is still a pointer to a #gint variable, not a #guchar; -g_socket_get_option() will handle the conversion internally. - - - success or failure. On failure, @error will be set, and - the system error value (`errno` or WSAGetLastError()) will still - be set to the result of the getsockopt() call. - - - - - a #GSocket - - - - the "API level" of the option (eg, `SOL_SOCKET`) - - - - the "name" of the option (eg, `SO_BROADCAST`) - - - - return location for the option value - - - - - - Gets the socket protocol id the socket was created with. -In case the protocol is unknown, -1 is returned. - - - a protocol id, or -1 if unknown - - - - - a #GSocket. - - - - - - Try to get the remote address of a connected socket. This is only -useful for connection oriented sockets that have been connected. - - - a #GSocketAddress or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GSocket. - - - - - - Gets the socket type of the socket. - - - a #GSocketType - - - - - a #GSocket. - - - - - - Gets the timeout setting of the socket. For details on this, see -g_socket_set_timeout(). - - - the timeout in seconds - - - - - a #GSocket. - - - - - - Gets the unicast time-to-live setting on @socket; see -g_socket_set_ttl() for more details. - - - the time-to-live setting on @socket - - - - - a #GSocket. - - - - - - Checks whether a socket is closed. - - - %TRUE if socket is closed, %FALSE otherwise - - - - - a #GSocket - - - - - - Check whether the socket is connected. This is only useful for -connection-oriented sockets. - -If using g_socket_shutdown(), this function will return %TRUE until the -socket has been shut down for reading and writing. If you do a non-blocking -connect, this function will not return %TRUE until after you call -g_socket_check_connect_result(). - - - %TRUE if socket is connected, %FALSE otherwise. - - - - - a #GSocket. - - - - - - Registers @socket to receive multicast messages sent to @group. -@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have -been bound to an appropriate interface and port with -g_socket_bind(). - -If @iface is %NULL, the system will automatically pick an interface -to bind to based on @group. - -If @source_specific is %TRUE, source-specific multicast as defined -in RFC 4604 is used. Note that on older platforms this may fail -with a %G_IO_ERROR_NOT_SUPPORTED error. - -To bind to a given source-specific multicast address, use -g_socket_join_multicast_group_ssm() instead. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - a #GInetAddress specifying the group address to join. - - - - %TRUE if source-specific multicast should be used - - - - Name of the interface to use, or %NULL - - - - - - Registers @socket to receive multicast messages sent to @group. -@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have -been bound to an appropriate interface and port with -g_socket_bind(). - -If @iface is %NULL, the system will automatically pick an interface -to bind to based on @group. - -If @source_specific is not %NULL, use source-specific multicast as -defined in RFC 4604. Note that on older platforms this may fail -with a %G_IO_ERROR_NOT_SUPPORTED error. - -Note that this function can be called multiple times for the same -@group with different @source_specific in order to receive multicast -packets from more than one source. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - a #GInetAddress specifying the group address to join. - - - - a #GInetAddress specifying the -source-specific multicast address or %NULL to ignore. - - - - Name of the interface to use, or %NULL - - - - - - Removes @socket from the multicast group defined by @group, @iface, -and @source_specific (which must all have the same values they had -when you joined the group). - -@socket remains bound to its address and port, and can still receive -unicast messages after calling this. - -To unbind to a given source-specific multicast address, use -g_socket_leave_multicast_group_ssm() instead. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - a #GInetAddress specifying the group address to leave. - - - - %TRUE if source-specific multicast was used - - - - Interface used - - - - - - Removes @socket from the multicast group defined by @group, @iface, -and @source_specific (which must all have the same values they had -when you joined the group). - -@socket remains bound to its address and port, and can still receive -unicast messages after calling this. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - a #GInetAddress specifying the group address to leave. - - - - a #GInetAddress specifying the -source-specific multicast address or %NULL to ignore. - - - - Name of the interface to use, or %NULL - - - - - - Marks the socket as a server socket, i.e. a socket that is used -to accept incoming requests using g_socket_accept(). - -Before calling this the socket must be bound to a local address using -g_socket_bind(). - -To set the maximum amount of outstanding clients, use -g_socket_set_listen_backlog(). - - - %TRUE on success, %FALSE on error. - - - - - a #GSocket. - - - - - - Receive data (up to @size bytes) from a socket. This is mainly used by -connection-oriented sockets; it is identical to g_socket_receive_from() -with @address set to %NULL. - -For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, -g_socket_receive() will always read either 0 or 1 complete messages from -the socket. If the received message is too large to fit in @buffer, then -the data beyond @size bytes will be discarded, without any explicit -indication that this has occurred. - -For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any -number of bytes, up to @size. If more than @size bytes have been -received, the additional data will be returned in future calls to -g_socket_receive(). - -If the socket is in blocking mode the call will block until there -is some data to receive, the connection is closed, or there is an -error. If there is no data available and the socket is in -non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be -returned. To be notified when data is available, wait for the -%G_IO_IN condition. - -On error -1 is returned and @error is set accordingly. - - - Number of bytes read, or 0 if the connection was closed by -the peer, or -1 on error - - - - - a #GSocket - - - - a buffer to - read data into (which should be at least @size bytes long). - - - - - - the number of bytes you want to read from the socket - - - - a %GCancellable or %NULL - - - - - - Receive data (up to @size bytes) from a socket. - -If @address is non-%NULL then @address will be set equal to the -source address of the received packet. -@address is owned by the caller. - -See g_socket_receive() for additional information. - - - Number of bytes read, or 0 if the connection was closed by -the peer, or -1 on error - - - - - a #GSocket - - - - a pointer to a #GSocketAddress - pointer, or %NULL - - - - a buffer to - read data into (which should be at least @size bytes long). - - - - - - the number of bytes you want to read from the socket - - - - a %GCancellable or %NULL - - - - - - Receive data from a socket. For receiving multiple messages, see -g_socket_receive_messages(); for easier use, see -g_socket_receive() and g_socket_receive_from(). - -If @address is non-%NULL then @address will be set equal to the -source address of the received packet. -@address is owned by the caller. - -@vector must point to an array of #GInputVector structs and -@num_vectors must be the length of this array. These structs -describe the buffers that received data will be scattered into. -If @num_vectors is -1, then @vectors is assumed to be terminated -by a #GInputVector with a %NULL buffer pointer. - -As a special case, if @num_vectors is 0 (in which case, @vectors -may of course be %NULL), then a single byte is received and -discarded. This is to facilitate the common practice of sending a -single '\0' byte for the purposes of transferring ancillary data. - -@messages, if non-%NULL, will be set to point to a newly-allocated -array of #GSocketControlMessage instances or %NULL if no such -messages was received. These correspond to the control messages -received from the kernel, one #GSocketControlMessage per message -from the kernel. This array is %NULL-terminated and must be freed -by the caller using g_free() after calling g_object_unref() on each -element. If @messages is %NULL, any control messages received will -be discarded. - -@num_messages, if non-%NULL, will be set to the number of control -messages received. - -If both @messages and @num_messages are non-%NULL, then -@num_messages gives the number of #GSocketControlMessage instances -in @messages (ie: not including the %NULL terminator). - -@flags is an in/out parameter. The commonly available arguments -for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too -(and g_socket_receive_message() may pass system-specific flags out). -Flags passed in to the parameter affect the receive operation; flags returned -out of it are relevant to the specific returned message. - -As with g_socket_receive(), data may be discarded if @socket is -%G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not -provide enough buffer space to read a complete message. You can pass -%G_SOCKET_MSG_PEEK in @flags to peek at the current message without -removing it from the receive queue, but there is no portable way to find -out the length of the message other than by reading it into a -sufficiently-large buffer. - -If the socket is in blocking mode the call will block until there -is some data to receive, the connection is closed, or there is an -error. If there is no data available and the socket is in -non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be -returned. To be notified when data is available, wait for the -%G_IO_IN condition. - -On error -1 is returned and @error is set accordingly. - - - Number of bytes read, or 0 if the connection was closed by -the peer, or -1 on error - - - - - a #GSocket - - - - a pointer to a #GSocketAddress - pointer, or %NULL - - - - an array of #GInputVector structs - - - - - - the number of elements in @vectors, or -1 - - - - a pointer - which may be filled with an array of #GSocketControlMessages, or %NULL - - - - - - a pointer which will be filled with the number of - elements in @messages, or %NULL - - - - a pointer to an int containing #GSocketMsgFlags flags, - which may additionally contain - [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - - - - a %GCancellable or %NULL - - - - - - Receive multiple data messages from @socket in one go. This is the most -complicated and fully-featured version of this call. For easier use, see -g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message(). - -@messages must point to an array of #GInputMessage structs and -@num_messages must be the length of this array. Each #GInputMessage -contains a pointer to an array of #GInputVector structs describing the -buffers that the data received in each message will be written to. Using -multiple #GInputVectors is more memory-efficient than manually copying data -out of a single buffer to multiple sources, and more system-call-efficient -than making multiple calls to g_socket_receive(), such as in scenarios where -a lot of data packets need to be received (e.g. high-bandwidth video -streaming over RTP/UDP). - -@flags modify how all messages are received. The commonly available -arguments for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. These -flags affect the overall receive operation. Flags affecting individual -messages are returned in #GInputMessage.flags. - -The other members of #GInputMessage are treated as described in its -documentation. - -If #GSocket:blocking is %TRUE the call will block until @num_messages have -been received, or the end of the stream is reached. - -If #GSocket:blocking is %FALSE the call will return up to @num_messages -without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the -operating system to be received. - -In blocking mode, if #GSocket:timeout is positive and is reached before any -messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to -@num_messages are returned. (Note: This is effectively the -behaviour of `MSG_WAITFORONE` with recvmmsg().) - -To be notified when messages are available, wait for the -%G_IO_IN condition. Note though that you may still receive -%G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were -previously notified of a %G_IO_IN condition. - -If the remote peer closes the connection, any messages queued in the -operating system will be returned, and subsequent calls to -g_socket_receive_messages() will return 0 (with no error set). - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be received; otherwise the number of -messages successfully received before the error will be returned. - - - number of messages received, or -1 on error. Note that the number - of messages received may be smaller than @num_messages if in non-blocking - mode, if the peer closed the connection, or if @num_messages - was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - to receive the remaining messages. - - - - - a #GSocket - - - - an array of #GInputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags for the overall operation, - which may additionally contain - [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - - - - a %GCancellable or %NULL - - - - - - This behaves exactly the same as g_socket_receive(), except that -the choice of blocking or non-blocking behavior is determined by -the @blocking argument rather than by @socket's properties. - - - Number of bytes read, or 0 if the connection was closed by -the peer, or -1 on error - - - - - a #GSocket - - - - a buffer to - read data into (which should be at least @size bytes long). - - - - - - the number of bytes you want to read from the socket - - - - whether to do blocking or non-blocking I/O - - - - a %GCancellable or %NULL - - - - - - Tries to send @size bytes from @buffer on the socket. This is -mainly used by connection-oriented sockets; it is identical to -g_socket_send_to() with @address set to %NULL. - -If the socket is in blocking mode the call will block until there is -space for the data in the socket queue. If there is no space available -and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error -will be returned. To be notified when space is available, wait for the -%G_IO_OUT condition. Note though that you may still receive -%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously -notified of a %G_IO_OUT condition. (On Windows in particular, this is -very common due to the way the underlying APIs work.) - -On error -1 is returned and @error is set accordingly. - - - Number of bytes written (which may be less than @size), or -1 -on error - - - - - a #GSocket - - - - the buffer - containing the data to send. - - - - - - the number of bytes to send - - - - a %GCancellable or %NULL - - - - - - Send data to @address on @socket. For sending multiple messages see -g_socket_send_messages(); for easier use, see -g_socket_send() and g_socket_send_to(). - -If @address is %NULL then the message is sent to the default receiver -(set by g_socket_connect()). - -@vectors must point to an array of #GOutputVector structs and -@num_vectors must be the length of this array. (If @num_vectors is -1, -then @vectors is assumed to be terminated by a #GOutputVector with a -%NULL buffer pointer.) The #GOutputVector structs describe the buffers -that the sent data will be gathered from. Using multiple -#GOutputVectors is more memory-efficient than manually copying -data from multiple sources into a single buffer, and more -network-efficient than making multiple calls to g_socket_send(). - -@messages, if non-%NULL, is taken to point to an array of @num_messages -#GSocketControlMessage instances. These correspond to the control -messages to be sent on the socket. -If @num_messages is -1 then @messages is treated as a %NULL-terminated -array. - -@flags modify how the message is sent. The commonly available arguments -for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. - -If the socket is in blocking mode the call will block until there is -space for the data in the socket queue. If there is no space available -and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error -will be returned. To be notified when space is available, wait for the -%G_IO_OUT condition. Note though that you may still receive -%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously -notified of a %G_IO_OUT condition. (On Windows in particular, this is -very common due to the way the underlying APIs work.) - -On error -1 is returned and @error is set accordingly. - - - Number of bytes written (which may be less than @size), or -1 -on error - - - - - a #GSocket - - - - a #GSocketAddress, or %NULL - - - - an array of #GOutputVector structs - - - - - - the number of elements in @vectors, or -1 - - - - a pointer to an - array of #GSocketControlMessages, or %NULL. - - - - - - number of elements in @messages, or -1. - - - - an int containing #GSocketMsgFlags flags, which may additionally - contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - - - - a %GCancellable or %NULL - - - - - - This behaves exactly the same as g_socket_send_message(), except that -the choice of timeout behavior is determined by the @timeout_us argument -rather than by @socket's properties. - -On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or -if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is -returned. @bytes_written will contain 0 in both cases. - - - %G_POLLABLE_RETURN_OK if all data was successfully written, -%G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or -%G_POLLABLE_RETURN_FAILED if an error happened and @error is set. - - - - - a #GSocket - - - - a #GSocketAddress, or %NULL - - - - an array of #GOutputVector structs - - - - - - the number of elements in @vectors, or -1 - - - - a pointer to an - array of #GSocketControlMessages, or %NULL. - - - - - - number of elements in @messages, or -1. - - - - an int containing #GSocketMsgFlags flags, which may additionally - contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - - - - the maximum time (in microseconds) to wait, or -1 - - - - location to store the number of bytes that were written to the socket - - - - a %GCancellable or %NULL - - - - - - Send multiple data messages from @socket in one go. This is the most -complicated and fully-featured version of this call. For easier use, see -g_socket_send(), g_socket_send_to(), and g_socket_send_message(). - -@messages must point to an array of #GOutputMessage structs and -@num_messages must be the length of this array. Each #GOutputMessage -contains an address to send the data to, and a pointer to an array of -#GOutputVector structs to describe the buffers that the data to be sent -for each message will be gathered from. Using multiple #GOutputVectors is -more memory-efficient than manually copying data from multiple sources -into a single buffer, and more network-efficient than making multiple -calls to g_socket_send(). Sending multiple messages in one go avoids the -overhead of making a lot of syscalls in scenarios where a lot of data -packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), -or where the same data needs to be sent to multiple recipients. - -@flags modify how the message is sent. The commonly available arguments -for this are available in the #GSocketMsgFlags enum, but the -values there are the same as the system values, and the flags -are passed in as-is, so you can pass in system-specific flags too. - -If the socket is in blocking mode the call will block until there is -space for all the data in the socket queue. If there is no space available -and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error -will be returned if no data was written at all, otherwise the number of -messages sent will be returned. To be notified when space is available, -wait for the %G_IO_OUT condition. Note though that you may still receive -%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously -notified of a %G_IO_OUT condition. (On Windows in particular, this is -very common due to the way the underlying APIs work.) - -On error -1 is returned and @error is set accordingly. An error will only -be returned if zero messages could be sent; otherwise the number of messages -successfully sent before the error will be returned. - - - number of messages sent, or -1 on error. Note that the number of - messages sent may be smaller than @num_messages if the socket is - non-blocking or if @num_messages was larger than UIO_MAXIOV (1024), - in which case the caller may re-try to send the remaining messages. - - - - - a #GSocket - - - - an array of #GOutputMessage structs - - - - - - the number of elements in @messages - - - - an int containing #GSocketMsgFlags flags, which may additionally - contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - - - - a %GCancellable or %NULL - - - - - - Tries to send @size bytes from @buffer to @address. If @address is -%NULL then the message is sent to the default receiver (set by -g_socket_connect()). - -See g_socket_send() for additional information. - - - Number of bytes written (which may be less than @size), or -1 -on error - - - - - a #GSocket - - - - a #GSocketAddress, or %NULL - - - - the buffer - containing the data to send. - - - - - - the number of bytes to send - - - - a %GCancellable or %NULL - - - - - - This behaves exactly the same as g_socket_send(), except that -the choice of blocking or non-blocking behavior is determined by -the @blocking argument rather than by @socket's properties. - - - Number of bytes written (which may be less than @size), or -1 -on error - - - - - a #GSocket - - - - the buffer - containing the data to send. - - - - - - the number of bytes to send - - - - whether to do blocking or non-blocking I/O - - - - a %GCancellable or %NULL - - - - - - Sets the blocking mode of the socket. In blocking mode -all operations (which don’t take an explicit blocking parameter) block until -they succeed or there is an error. In -non-blocking mode all functions return results immediately or -with a %G_IO_ERROR_WOULD_BLOCK error. - -All sockets are created in blocking mode. However, note that the -platform level socket is always non-blocking, and blocking mode -is a GSocket level feature. - - - - - - - a #GSocket. - - - - Whether to use blocking I/O or not. - - - - - - Sets whether @socket should allow sending to broadcast addresses. -This is %FALSE by default. - - - - - - - a #GSocket. - - - - whether @socket should allow sending to broadcast - addresses - - - - - - Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When -this flag is set on a socket, the system will attempt to verify that the -remote socket endpoint is still present if a sufficiently long period of -time passes with no data being exchanged. If the system is unable to -verify the presence of the remote endpoint, it will automatically close -the connection. - -This option is only functional on certain kinds of sockets. (Notably, -%G_SOCKET_PROTOCOL_TCP sockets.) - -The exact time between pings is system- and protocol-dependent, but will -normally be at least two hours. Most commonly, you would set this flag -on a server socket if you want to allow clients to remain idle for long -periods of time, but also want to ensure that connections are eventually -garbage-collected if clients crash or become unreachable. - - - - - - - a #GSocket. - - - - Value for the keepalive flag - - - - - - Sets the maximum number of outstanding connections allowed -when listening on this socket. If more clients than this are -connecting to the socket and the application is not handling them -on time then the new connections will be refused. - -Note that this must be called before g_socket_listen() and has no -effect if called after that. - - - - - - - a #GSocket. - - - - the maximum number of pending connections. - - - - - - Sets whether outgoing multicast packets will be received by sockets -listening on that multicast address on the same host. This is %TRUE -by default. - - - - - - - a #GSocket. - - - - whether @socket should receive messages sent to its - multicast groups from the local host - - - - - - Sets the time-to-live for outgoing multicast datagrams on @socket. -By default, this is 1, meaning that multicast packets will not leave -the local network. - - - - - - - a #GSocket. - - - - the time-to-live value for all multicast datagrams on @socket - - - - - - Sets the value of an integer-valued option on @socket, as with -setsockopt(). (If you need to set a non-integer-valued option, -you will need to call setsockopt() directly.) - -The [<gio/gnetworking.h>][gio-gnetworking.h] -header pulls in system headers that will define most of the -standard/portable socket options. For unusual socket protocols or -platform-dependent options, you may need to include additional -headers. - - - success or failure. On failure, @error will be set, and - the system error value (`errno` or WSAGetLastError()) will still - be set to the result of the setsockopt() call. - - - - - a #GSocket - - - - the "API level" of the option (eg, `SOL_SOCKET`) - - - - the "name" of the option (eg, `SO_BROADCAST`) - - - - the value to set the option to - - - - - - Sets the time in seconds after which I/O operations on @socket will -time out if they have not yet completed. - -On a blocking socket, this means that any blocking #GSocket -operation will time out after @timeout seconds of inactivity, -returning %G_IO_ERROR_TIMED_OUT. - -On a non-blocking socket, calls to g_socket_condition_wait() will -also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources -created with g_socket_create_source() will trigger after -@timeout seconds of inactivity, with the requested condition -set, at which point calling g_socket_receive(), g_socket_send(), -g_socket_check_connect_result(), etc, will fail with -%G_IO_ERROR_TIMED_OUT. - -If @timeout is 0 (the default), operations will never time out -on their own. - -Note that if an I/O operation is interrupted by a signal, this may -cause the timeout to be reset. - - - - - - - a #GSocket. - - - - the timeout for @socket, in seconds, or 0 for none - - - - - - Sets the time-to-live for outgoing unicast packets on @socket. -By default the platform-specific default value is used. - - - - - - - a #GSocket. - - - - the time-to-live value for all unicast packets on @socket - - - - - - Shut down part or all of a full-duplex connection. - -If @shutdown_read is %TRUE then the receiving side of the connection -is shut down, and further reading is disallowed. - -If @shutdown_write is %TRUE then the sending side of the connection -is shut down, and further writing is disallowed. - -It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. - -One example where it is useful to shut down only one side of a connection is -graceful disconnect for TCP connections where you close the sending side, -then wait for the other side to close the connection, thus ensuring that the -other side saw all sent data. - - - %TRUE on success, %FALSE on error - - - - - a #GSocket - - - - whether to shut down the read side - - - - whether to shut down the write side - - - - - - Checks if a socket is capable of speaking IPv4. - -IPv4 sockets are capable of speaking IPv4. On some operating systems -and under some combinations of circumstances IPv6 sockets are also -capable of speaking IPv4. See RFC 3493 section 3.7 for more -information. - -No other types of sockets are currently considered as being capable -of speaking IPv4. - - - %TRUE if this socket can be used with IPv4. - - - - - a #GSocket - - - - - - - - - Whether the socket should allow sending to broadcast addresses. - - - - - - - - - - - - - - - - - - - Whether outgoing multicast packets loop back to the local host. - - - - Time-to-live out outgoing multicast packets - - - - - - - - - - The timeout in seconds on socket I/O - - - - Time-to-live for outgoing unicast packets - - - - - - - - - - - - - - #GSocketAddress is the equivalent of struct sockaddr in the BSD -sockets API. This is an abstract class; use #GInetSocketAddress -for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. - - - - Creates a #GSocketAddress subclass corresponding to the native -struct sockaddr @native. - - - a new #GSocketAddress if @native could successfully - be converted, otherwise %NULL - - - - - a pointer to a struct sockaddr - - - - the size of the memory location pointed to by @native - - - - - - Gets the socket family type of @address. - - - the socket family type of @address - - - - - a #GSocketAddress - - - - - - Gets the size of @address's native struct sockaddr. -You can use this to allocate memory to pass to -g_socket_address_to_native(). - - - the size of the native struct sockaddr that - @address represents - - - - - a #GSocketAddress - - - - - - Converts a #GSocketAddress to a native struct sockaddr, which can -be passed to low-level functions like connect() or bind(). - -If not enough space is available, a %G_IO_ERROR_NO_SPACE error -is returned. If the address type is not known on the system -then a %G_IO_ERROR_NOT_SUPPORTED error is returned. - - - %TRUE if @dest was filled in, %FALSE on error - - - - - a #GSocketAddress - - - - a pointer to a memory location that will contain the native -struct sockaddr - - - - the size of @dest. Must be at least as large as - g_socket_address_get_native_size() - - - - - - Gets the socket family type of @address. - - - the socket family type of @address - - - - - a #GSocketAddress - - - - - - Gets the size of @address's native struct sockaddr. -You can use this to allocate memory to pass to -g_socket_address_to_native(). - - - the size of the native struct sockaddr that - @address represents - - - - - a #GSocketAddress - - - - - - Converts a #GSocketAddress to a native struct sockaddr, which can -be passed to low-level functions like connect() or bind(). - -If not enough space is available, a %G_IO_ERROR_NO_SPACE error -is returned. If the address type is not known on the system -then a %G_IO_ERROR_NOT_SUPPORTED error is returned. - - - %TRUE if @dest was filled in, %FALSE on error - - - - - a #GSocketAddress - - - - a pointer to a memory location that will contain the native -struct sockaddr - - - - the size of @dest. Must be at least as large as - g_socket_address_get_native_size() - - - - - - - - - - - - - - - - - - - - - the socket family type of @address - - - - - a #GSocketAddress - - - - - - - - - - the size of the native struct sockaddr that - @address represents - - - - - a #GSocketAddress - - - - - - - - - - %TRUE if @dest was filled in, %FALSE on error - - - - - a #GSocketAddress - - - - a pointer to a memory location that will contain the native -struct sockaddr - - - - the size of @dest. Must be at least as large as - g_socket_address_get_native_size() - - - - - - - - #GSocketAddressEnumerator is an enumerator type for #GSocketAddress -instances. It is returned by enumeration functions such as -g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator -to list each #GSocketAddress which could be used to connect to that -#GSocketConnectable. - -Enumeration is typically a blocking operation, so the asynchronous methods -g_socket_address_enumerator_next_async() and -g_socket_address_enumerator_next_finish() should be used where possible. - -Each #GSocketAddressEnumerator can only be enumerated once. Once -g_socket_address_enumerator_next() has returned %NULL (and no error), further -enumeration with that #GSocketAddressEnumerator is not possible, and it can -be unreffed. - - - Retrieves the next #GSocketAddress from @enumerator. Note that this -may block for some amount of time. (Eg, a #GNetworkAddress may need -to do a DNS lookup before it can return an address.) Use -g_socket_address_enumerator_next_async() if you need to avoid -blocking. - -If @enumerator is expected to yield addresses, but for some reason -is unable to (eg, because of a DNS error), then the first call to -g_socket_address_enumerator_next() will return an appropriate error -in *@error. However, if the first call to -g_socket_address_enumerator_next() succeeds, then any further -internal errors (other than @cancellable being triggered) will be -ignored. - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously retrieves the next #GSocketAddress from @enumerator -and then calls @callback, which must call -g_socket_address_enumerator_next_finish() to get the result. - -It is an error to call this multiple times before the previous callback has finished. - - - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request - is satisfied - - - - the data to pass to callback function - - - - - - Retrieves the result of a completed call to -g_socket_address_enumerator_next_async(). See -g_socket_address_enumerator_next() for more information about -error handling. - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - a #GAsyncResult - - - - - - Retrieves the next #GSocketAddress from @enumerator. Note that this -may block for some amount of time. (Eg, a #GNetworkAddress may need -to do a DNS lookup before it can return an address.) Use -g_socket_address_enumerator_next_async() if you need to avoid -blocking. - -If @enumerator is expected to yield addresses, but for some reason -is unable to (eg, because of a DNS error), then the first call to -g_socket_address_enumerator_next() will return an appropriate error -in *@error. However, if the first call to -g_socket_address_enumerator_next() succeeds, then any further -internal errors (other than @cancellable being triggered) will be -ignored. - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Asynchronously retrieves the next #GSocketAddress from @enumerator -and then calls @callback, which must call -g_socket_address_enumerator_next_finish() to get the result. - -It is an error to call this multiple times before the previous callback has finished. - - - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request - is satisfied - - - - the data to pass to callback function - - - - - - Retrieves the result of a completed call to -g_socket_address_enumerator_next_async(). See -g_socket_address_enumerator_next() for more information about -error handling. - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - a #GAsyncResult - - - - - - - - - - Class structure for #GSocketAddressEnumerator. - - - - - - - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - a #GSocketAddressEnumerator - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request - is satisfied - - - - the data to pass to callback function - - - - - - - - - - a #GSocketAddress (owned by the caller), or %NULL on - error (in which case *@error will be set) or if there are no - more addresses. - - - - - a #GSocketAddressEnumerator - - - - a #GAsyncResult - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GSocketClient is a lightweight high-level utility class for connecting to -a network host using a connection oriented socket type. - -You create a #GSocketClient object, set any options you want, and then -call a sync or async connect operation, which returns a #GSocketConnection -subclass on success. - -The type of the #GSocketConnection object returned depends on the type of -the underlying socket that is in use. For instance, for a TCP/IP connection -it will be a #GTcpConnection. - -As #GSocketClient is a lightweight object, you don't need to cache it. You -can just create a new one any time you need one. - - - Creates a new #GSocketClient with the default options. - - - a #GSocketClient. - Free the returned object with g_object_unref(). - - - - - - - - - - - - - - - - - - - - - - - - - Enable proxy protocols to be handled by the application. When the -indicated proxy protocol is returned by the #GProxyResolver, -#GSocketClient will consider this protocol as supported but will -not try to find a #GProxy instance to handle handshaking. The -application must check for this case by calling -g_socket_connection_get_remote_address() on the returned -#GSocketConnection, and seeing if it's a #GProxyAddress of the -appropriate type, to determine whether or not it needs to handle -the proxy handshaking itself. - -This should be used for proxy protocols that are dialects of -another protocol such as HTTP proxy. It also allows cohabitation of -proxy protocols that are reused between protocols. A good example -is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also -be use as generic socket proxy through the HTTP CONNECT method. - -When the proxy is detected as being an application proxy, TLS handshake -will be skipped. This is required to let the application do the proxy -specific handshake. - - - - - - - a #GSocketClient - - - - The proxy protocol - - - - - - Tries to resolve the @connectable and make a network connection to it. - -Upon a successful connection, a new #GSocketConnection is constructed -and returned. The caller owns this new object and must drop their -reference to it when finished with it. - -The type of the #GSocketConnection object returned depends on the type of -the underlying socket that is used. For instance, for a TCP/IP connection -it will be a #GTcpConnection. - -The socket created will be the same family as the address that the -@connectable resolves to, unless family is set with g_socket_client_set_family() -or indirectly via g_socket_client_set_local_address(). The socket type -defaults to %G_SOCKET_TYPE_STREAM but can be set with -g_socket_client_set_socket_type(). - -If a local address is specified with g_socket_client_set_local_address() the -socket will be bound to this address before connecting. - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient. - - - - a #GSocketConnectable specifying the remote address. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - This is the asynchronous version of g_socket_client_connect(). - -When the operation is finished @callback will be -called. You can then call g_socket_client_connect_finish() to get -the result of the operation. - - - - - - - a #GSocketClient - - - - a #GSocketConnectable specifying the remote address. - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async connect operation. See g_socket_client_connect_async() - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient. - - - - a #GAsyncResult. - - - - - - This is a helper function for g_socket_client_connect(). - -Attempts to create a TCP connection to the named host. - -@host_and_port may be in any of a number of recognized formats; an IPv6 -address, an IPv4 address, or a domain name (in which case a DNS -lookup is performed). Quoting with [] is supported for all address -types. A port override may be specified in the usual way with a -colon. Ports may be given as decimal numbers or symbolic names (in -which case an /etc/services lookup is performed). - -If no port override is given in @host_and_port then @default_port will be -used as the port number to connect to. - -In general, @host_and_port is expected to be provided by the user (allowing -them to give the hostname, and a port override if necessary) and -@default_port is expected to be provided by the application. - -In the case that an IP address is given, a single connection -attempt is made. In the case that a name is given, multiple -connection attempts may be made, in turn and according to the -number of address records in DNS, until a connection succeeds. - -Upon a successful connection, a new #GSocketConnection is constructed -and returned. The caller owns this new object and must drop their -reference to it when finished with it. - -In the event of any failure (DNS error, service not found, no hosts -connectable) %NULL is returned and @error (if non-%NULL) is set -accordingly. - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient - - - - the name and optionally port of the host to connect to - - - - the default port to connect to - - - - a #GCancellable, or %NULL - - - - - - This is the asynchronous version of g_socket_client_connect_to_host(). - -When the operation is finished @callback will be -called. You can then call g_socket_client_connect_to_host_finish() to get -the result of the operation. - - - - - - - a #GSocketClient - - - - the name and optionally the port of the host to connect to - - - - the default port to connect to - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async connect operation. See g_socket_client_connect_to_host_async() - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient. - - - - a #GAsyncResult. - - - - - - Attempts to create a TCP connection to a service. - -This call looks up the SRV record for @service at @domain for the -"tcp" protocol. It then attempts to connect, in turn, to each of -the hosts providing the service until either a connection succeeds -or there are no hosts remaining. - -Upon a successful connection, a new #GSocketConnection is constructed -and returned. The caller owns this new object and must drop their -reference to it when finished with it. - -In the event of any failure (DNS error, service not found, no hosts -connectable) %NULL is returned and @error (if non-%NULL) is set -accordingly. - - - a #GSocketConnection if successful, or %NULL on error - - - - - a #GSocketConnection - - - - a domain name - - - - the name of the service to connect to - - - - a #GCancellable, or %NULL - - - - - - This is the asynchronous version of -g_socket_client_connect_to_service(). - - - - - - - a #GSocketClient - - - - a domain name - - - - the name of the service to connect to - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async connect operation. See g_socket_client_connect_to_service_async() - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient. - - - - a #GAsyncResult. - - - - - - This is a helper function for g_socket_client_connect(). - -Attempts to create a TCP connection with a network URI. - -@uri may be any valid URI containing an "authority" (hostname/port) -component. If a port is not specified in the URI, @default_port -will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE. -(#GSocketClient does not know to automatically assume TLS for -certain URI schemes.) - -Using this rather than g_socket_client_connect() or -g_socket_client_connect_to_host() allows #GSocketClient to -determine when to use application-specific proxy protocols. - -Upon a successful connection, a new #GSocketConnection is constructed -and returned. The caller owns this new object and must drop their -reference to it when finished with it. - -In the event of any failure (DNS error, service not found, no hosts -connectable) %NULL is returned and @error (if non-%NULL) is set -accordingly. - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient - - - - A network URI - - - - the default port to connect to - - - - a #GCancellable, or %NULL - - - - - - This is the asynchronous version of g_socket_client_connect_to_uri(). - -When the operation is finished @callback will be -called. You can then call g_socket_client_connect_to_uri_finish() to get -the result of the operation. - - - - - - - a #GSocketClient - - - - a network uri - - - - the default port to connect to - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async connect operation. See g_socket_client_connect_to_uri_async() - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketClient. - - - - a #GAsyncResult. - - - - - - Gets the proxy enable state; see g_socket_client_set_enable_proxy() - - - whether proxying is enabled - - - - - a #GSocketClient. - - - - - - Gets the socket family of the socket client. - -See g_socket_client_set_family() for details. - - - a #GSocketFamily - - - - - a #GSocketClient. - - - - - - Gets the local address of the socket client. - -See g_socket_client_set_local_address() for details. - - - a #GSocketAddress or %NULL. Do not free. - - - - - a #GSocketClient. - - - - - - Gets the protocol name type of the socket client. - -See g_socket_client_set_protocol() for details. - - - a #GSocketProtocol - - - - - a #GSocketClient - - - - - - Gets the #GProxyResolver being used by @client. Normally, this will -be the resolver returned by g_proxy_resolver_get_default(), but you -can override it with g_socket_client_set_proxy_resolver(). - - - The #GProxyResolver being used by - @client. - - - - - a #GSocketClient. - - - - - - Gets the socket type of the socket client. - -See g_socket_client_set_socket_type() for details. - - - a #GSocketFamily - - - - - a #GSocketClient. - - - - - - Gets the I/O timeout time for sockets created by @client. - -See g_socket_client_set_timeout() for details. - - - the timeout in seconds - - - - - a #GSocketClient - - - - - - Gets whether @client creates TLS connections. See -g_socket_client_set_tls() for details. - - - whether @client uses TLS - - - - - a #GSocketClient. - - - - - - Gets the TLS validation flags used creating TLS connections via -@client. - - - the TLS validation flags - - - - - a #GSocketClient. - - - - - - Sets whether or not @client attempts to make connections via a -proxy server. When enabled (the default), #GSocketClient will use a -#GProxyResolver to determine if a proxy protocol such as SOCKS is -needed, and automatically do the necessary proxy negotiation. - -See also g_socket_client_set_proxy_resolver(). - - - - - - - a #GSocketClient. - - - - whether to enable proxies - - - - - - Sets the socket family of the socket client. -If this is set to something other than %G_SOCKET_FAMILY_INVALID -then the sockets created by this object will be of the specified -family. - -This might be useful for instance if you want to force the local -connection to be an ipv4 socket, even though the address might -be an ipv6 mapped to ipv4 address. - - - - - - - a #GSocketClient. - - - - a #GSocketFamily - - - - - - Sets the local address of the socket client. -The sockets created by this object will bound to the -specified address (if not %NULL) before connecting. - -This is useful if you want to ensure that the local -side of the connection is on a specific port, or on -a specific interface. - - - - - - - a #GSocketClient. - - - - a #GSocketAddress, or %NULL - - - - - - Sets the protocol of the socket client. -The sockets created by this object will use of the specified -protocol. - -If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default -protocol for the socket family and type. - - - - - - - a #GSocketClient. - - - - a #GSocketProtocol - - - - - - Overrides the #GProxyResolver used by @client. You can call this if -you want to use specific proxies, rather than using the system -default proxy settings. - -Note that whether or not the proxy resolver is actually used -depends on the setting of #GSocketClient:enable-proxy, which is not -changed by this function (but which is %TRUE by default) - - - - - - - a #GSocketClient. - - - - a #GProxyResolver, or %NULL for the - default. - - - - - - Sets the socket type of the socket client. -The sockets created by this object will be of the specified -type. - -It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, -as GSocketClient is used for connection oriented services. - - - - - - - a #GSocketClient. - - - - a #GSocketType - - - - - - Sets the I/O timeout for sockets created by @client. @timeout is a -time in seconds, or 0 for no timeout (the default). - -The timeout value affects the initial connection attempt as well, -so setting this may cause calls to g_socket_client_connect(), etc, -to fail with %G_IO_ERROR_TIMED_OUT. - - - - - - - a #GSocketClient. - - - - the timeout - - - - - - Sets whether @client creates TLS (aka SSL) connections. If @tls is -%TRUE, @client will wrap its connections in a #GTlsClientConnection -and perform a TLS handshake when connecting. - -Note that since #GSocketClient must return a #GSocketConnection, -but #GTlsClientConnection is not a #GSocketConnection, this -actually wraps the resulting #GTlsClientConnection in a -#GTcpWrapperConnection when returning it. You can use -g_tcp_wrapper_connection_get_base_io_stream() on the return value -to extract the #GTlsClientConnection. - -If you need to modify the behavior of the TLS handshake (eg, by -setting a client-side certificate to use, or connecting to the -#GTlsConnection::accept-certificate signal), you can connect to -@client's #GSocketClient::event signal and wait for it to be -emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you -a chance to see the #GTlsClientConnection before the handshake -starts. - - - - - - - a #GSocketClient. - - - - whether to use TLS - - - - - - Sets the TLS validation flags used when creating TLS connections -via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. - - - - - - - a #GSocketClient. - - - - the validation flags - - - - - - - - - - - - - - - - - - The proxy resolver to use - - - - - - - - - - - - - - - - - - - - - - Emitted when @client's activity on @connectable changes state. -Among other things, this can be used to provide progress -information about a network connection in the UI. The meanings of -the different @event values are as follows: - -- %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable - in DNS. @connection will be %NULL. - -- %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved - @connectable in DNS. @connection will be %NULL. - -- %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection - to a remote host; either a proxy server or the destination server - itself. @connection is the #GSocketConnection, which is not yet - connected. Since GLib 2.40, you can access the remote - address via g_socket_connection_get_remote_address(). - -- %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected - to a remote host. @connection is the connected #GSocketConnection. - -- %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate - with a proxy to get it to connect to @connectable. @connection is - the #GSocketConnection to the proxy server. - -- %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a - connection to @connectable through a proxy server. @connection is - the stream returned from g_proxy_connect(), which may or may not - be a #GSocketConnection. - -- %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS - handshake. @connection is a #GTlsClientConnection. - -- %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed - the TLS handshake. @connection is a #GTlsClientConnection. - -- %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected - to @connectable (in which case @connection is the #GSocketConnection - that it will be returning to the caller) or has failed (in which - case @connection is %NULL and the client is about to return an error). - -Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted -multiple times (or not at all) for a given connectable (in -particular, if @client ends up attempting to connect to more than -one address). However, if @client emits the #GSocketClient::event -signal at all for a given connectable, that it will always emit -it with %G_SOCKET_CLIENT_COMPLETE when it is done. - -Note that there may be additional #GSocketClientEvent values in -the future; unrecognized @event values should be ignored. - - - - - - the event that is occurring - - - - the #GSocketConnectable that @event is occurring on - - - - the current representation of the connection - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Describes an event occurring on a #GSocketClient. See the -#GSocketClient::event signal for more details. - -Additional values may be added to this type in the future. - - The client is doing a DNS lookup. - - - The client has completed a DNS lookup. - - - The client is connecting to a remote - host (either a proxy or the destination server). - - - The client has connected to a remote - host. - - - The client is negotiating - with a proxy to connect to the destination server. - - - The client has negotiated - with the proxy server. - - - The client is performing a - TLS handshake. - - - The client has performed a - TLS handshake. - - - The client is done with a particular - #GSocketConnectable. - - - - - - - Objects that describe one or more potential socket endpoints -implement #GSocketConnectable. Callers can then use -g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator -to try out each socket address in turn until one succeeds, as shown -in the sample code below. - -|[<!-- language="C" --> -MyConnectionType * -connect_to_host (const char *hostname, - guint16 port, - GCancellable *cancellable, - GError **error) -{ - MyConnection *conn = NULL; - GSocketConnectable *addr; - GSocketAddressEnumerator *enumerator; - GSocketAddress *sockaddr; - GError *conn_error = NULL; - - addr = g_network_address_new (hostname, port); - enumerator = g_socket_connectable_enumerate (addr); - g_object_unref (addr); - - // Try each sockaddr until we succeed. Record the first connection error, - // but not any further ones (since they'll probably be basically the same - // as the first). - while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) - { - conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); - g_object_unref (sockaddr); - } - g_object_unref (enumerator); - - if (conn) - { - if (conn_error) - { - // We couldn't connect to the first address, but we succeeded - // in connecting to a later address. - g_error_free (conn_error); - } - return conn; - } - else if (error) - { - /// Either initial lookup failed, or else the caller cancelled us. - if (conn_error) - g_error_free (conn_error); - return NULL; - } - else - { - g_error_propagate (error, conn_error); - return NULL; - } -} -]| - - - Creates a #GSocketAddressEnumerator for @connectable. - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - Creates a #GSocketAddressEnumerator for @connectable that will -return a #GProxyAddress for each of its addresses that you must connect -to via a proxy. - -If @connectable does not implement -g_socket_connectable_proxy_enumerate(), this will fall back to -calling g_socket_connectable_enumerate(). - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - Format a #GSocketConnectable as a string. This is a human-readable format for -use in debugging output, and is not a stable serialization format. It is not -suitable for use in user interfaces as it exposes too much information for a -user. - -If the #GSocketConnectable implementation does not support string formatting, -the implementation’s type name will be returned as a fallback. - - - the formatted string - - - - - a #GSocketConnectable - - - - - - Creates a #GSocketAddressEnumerator for @connectable. - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - Creates a #GSocketAddressEnumerator for @connectable that will -return a #GProxyAddress for each of its addresses that you must connect -to via a proxy. - -If @connectable does not implement -g_socket_connectable_proxy_enumerate(), this will fall back to -calling g_socket_connectable_enumerate(). - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - Format a #GSocketConnectable as a string. This is a human-readable format for -use in debugging output, and is not a stable serialization format. It is not -suitable for use in user interfaces as it exposes too much information for a -user. - -If the #GSocketConnectable implementation does not support string formatting, -the implementation’s type name will be returned as a fallback. - - - the formatted string - - - - - a #GSocketConnectable - - - - - - - Provides an interface for returning a #GSocketAddressEnumerator -and #GProxyAddressEnumerator - - - The parent interface. - - - - - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - - - - - a new #GSocketAddressEnumerator. - - - - - a #GSocketConnectable - - - - - - - - - - the formatted string - - - - - a #GSocketConnectable - - - - - - - - #GSocketConnection is a #GIOStream for a connected socket. They -can be created either by #GSocketClient when connecting to a host, -or by #GSocketListener when accepting a new client. - -The type of the #GSocketConnection object returned from these calls -depends on the type of the underlying socket that is in use. For -instance, for a TCP/IP connection it will be a #GTcpConnection. - -Choosing what type of object to construct is done with the socket -connection factory, and it is possible for 3rd parties to register -custom socket connection types for specific combination of socket -family/type/protocol using g_socket_connection_factory_register_type(). - -To close a #GSocketConnection, use g_io_stream_close(). Closing both -substreams of the #GIOStream separately will not close the underlying -#GSocket. - - - Looks up the #GType to be used when creating socket connections on -sockets with the specified @family, @type and @protocol_id. - -If no type is registered, the #GSocketConnection base type is returned. - - - a #GType - - - - - a #GSocketFamily - - - - a #GSocketType - - - - a protocol id - - - - - - Looks up the #GType to be used when creating socket connections on -sockets with the specified @family, @type and @protocol. - -If no type is registered, the #GSocketConnection base type is returned. - - - - - - - a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION - - - - a #GSocketFamily - - - - a #GSocketType - - - - a protocol id - - - - - - Connect @connection to the specified remote address. - - - %TRUE if the connection succeeded, %FALSE on error - - - - - a #GSocketConnection - - - - a #GSocketAddress specifying the remote address. - - - - a %GCancellable or %NULL - - - - - - Asynchronously connect @connection to the specified remote address. - -This clears the #GSocket:blocking flag on @connection's underlying -socket if it is currently set. - -Use g_socket_connection_connect_finish() to retrieve the result. - - - - - - - a #GSocketConnection - - - - a #GSocketAddress specifying the remote address. - - - - a %GCancellable or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Gets the result of a g_socket_connection_connect_async() call. - - - %TRUE if the connection succeeded, %FALSE on error - - - - - a #GSocketConnection - - - - the #GAsyncResult - - - - - - Try to get the local address of a socket connection. - - - a #GSocketAddress or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GSocketConnection - - - - - - Try to get the remote address of a socket connection. - -Since GLib 2.40, when used with g_socket_client_connect() or -g_socket_client_connect_async(), during emission of -%G_SOCKET_CLIENT_CONNECTING, this function will return the remote -address that will be used for the connection. This allows -applications to print e.g. "Connecting to example.com -(10.42.77.3)...". - - - a #GSocketAddress or %NULL on error. - Free the returned object with g_object_unref(). - - - - - a #GSocketConnection - - - - - - Gets the underlying #GSocket object of the connection. -This can be useful if you want to do something unusual on it -not supported by the #GSocketConnection APIs. - - - a #GSocket or %NULL on error. - - - - - a #GSocketConnection - - - - - - Checks if @connection is connected. This is equivalent to calling -g_socket_is_connected() on @connection's underlying #GSocket. - - - whether @connection is connected - - - - - a #GSocketConnection - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GSocketControlMessage is a special-purpose utility message that -can be sent to or received from a #GSocket. These types of -messages are often called "ancillary data". - -The message can represent some sort of special instruction to or -information from the socket or can represent a special kind of -transfer to the peer (for example, sending a file descriptor over -a UNIX socket). - -These messages are sent with g_socket_send_message() and received -with g_socket_receive_message(). - -To extend the set of control message that can be sent, subclass this -class and override the get_size, get_level, get_type and serialize -methods. - -To extend the set of control messages that can be received, subclass -this class and implement the deserialize method. Also, make sure your -class is registered with the GType typesystem before calling -g_socket_receive_message() to read such a message. - - - Tries to deserialize a socket control message of a given -@level and @type. This will ask all known (to GType) subclasses -of #GSocketControlMessage if they can understand this kind -of message and if so deserialize it into a #GSocketControlMessage. - -If there is no implementation for this kind of control message, %NULL -will be returned. - - - the deserialized message or %NULL - - - - - a socket level - - - - a socket control message type for the given @level - - - - the size of the data in bytes - - - - pointer to the message data - - - - - - - - Returns the "level" (i.e. the originating protocol) of the control message. -This is often SOL_SOCKET. - - - an integer describing the level - - - - - a #GSocketControlMessage - - - - - - Returns the space required for the control message, not including -headers or alignment. - - - The number of bytes required. - - - - - a #GSocketControlMessage - - - - - - - - - - - - - - - - - Converts the data in the message to bytes placed in the -message. - -@data is guaranteed to have enough space to fit the size -returned by g_socket_control_message_get_size() on this -object. - - - - - - - a #GSocketControlMessage - - - - A buffer to write data to - - - - - - Returns the "level" (i.e. the originating protocol) of the control message. -This is often SOL_SOCKET. - - - an integer describing the level - - - - - a #GSocketControlMessage - - - - - - Returns the protocol specific type of the control message. -For instance, for UNIX fd passing this would be SCM_RIGHTS. - - - an integer describing the type of control message - - - - - a #GSocketControlMessage - - - - - - Returns the space required for the control message, not including -headers or alignment. - - - The number of bytes required. - - - - - a #GSocketControlMessage - - - - - - Converts the data in the message to bytes placed in the -message. - -@data is guaranteed to have enough space to fit the size -returned by g_socket_control_message_get_size() on this -object. - - - - - - - a #GSocketControlMessage - - - - A buffer to write data to - - - - - - - - - - - - - Class structure for #GSocketControlMessage. - - - - - - - - - The number of bytes required. - - - - - a #GSocketControlMessage - - - - - - - - - - an integer describing the level - - - - - a #GSocketControlMessage - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GSocketControlMessage - - - - A buffer to write data to - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The protocol family of a #GSocketAddress. (These values are -identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, -if available.) - - no address family - - - the UNIX domain family - - - the IPv4 family - - - the IPv6 family - - - - A #GSocketListener is an object that keeps track of a set -of server sockets and helps you accept sockets from any of the -socket, either sync or async. - -Add addresses and ports to listen on using g_socket_listener_add_address() -and g_socket_listener_add_inet_port(). These will be listened on until -g_socket_listener_close() is called. Dropping your final reference to the -#GSocketListener will not cause g_socket_listener_close() to be called -implicitly, as some references to the #GSocketListener may be held -internally. - -If you want to implement a network server, also look at #GSocketService -and #GThreadedSocketService which are subclasses of #GSocketListener -that make this even easier. - - - Creates a new #GSocketListener with no sockets to listen for. -New listeners can be added with e.g. g_socket_listener_add_address() -or g_socket_listener_add_inet_port(). - - - a new #GSocketListener. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Blocks waiting for a client to connect to any of the sockets added -to the listener. Returns a #GSocketConnection for the socket that was -accepted. - -If @source_object is not %NULL it will be filled out with the source -object specified when the corresponding socket or address was added -to the listener. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketListener - - - - location where #GObject pointer will be stored, or %NULL - - - - optional #GCancellable object, %NULL to ignore. - - - - - - This is the asynchronous version of g_socket_listener_accept(). - -When the operation is finished @callback will be -called. You can then call g_socket_listener_accept_socket() -to get the result of the operation. - - - - - - - a #GSocketListener - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async accept operation. See g_socket_listener_accept_async() - - - a #GSocketConnection on success, %NULL on error. - - - - - a #GSocketListener - - - - a #GAsyncResult. - - - - Optional #GObject identifying this source - - - - - - Blocks waiting for a client to connect to any of the sockets added -to the listener. Returns the #GSocket that was accepted. - -If you want to accept the high-level #GSocketConnection, not a #GSocket, -which is often the case, then you should use g_socket_listener_accept() -instead. - -If @source_object is not %NULL it will be filled out with the source -object specified when the corresponding socket or address was added -to the listener. - -If @cancellable is not %NULL, then the operation can be cancelled by -triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - - - a #GSocket on success, %NULL on error. - - - - - a #GSocketListener - - - - location where #GObject pointer will be stored, or %NULL. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - This is the asynchronous version of g_socket_listener_accept_socket(). - -When the operation is finished @callback will be -called. You can then call g_socket_listener_accept_socket_finish() -to get the result of the operation. - - - - - - - a #GSocketListener - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback - - - - user data for the callback - - - - - - Finishes an async accept operation. See g_socket_listener_accept_socket_async() - - - a #GSocket on success, %NULL on error. - - - - - a #GSocketListener - - - - a #GAsyncResult. - - - - Optional #GObject identifying this source - - - - - - Creates a socket of type @type and protocol @protocol, binds -it to @address and adds it to the set of sockets we're accepting -sockets from. - -Note that adding an IPv6 address, depending on the platform, -may or may not result in a listener that also accepts IPv4 -connections. For more deterministic behavior, see -g_socket_listener_add_inet_port(). - -@source_object will be passed out in the various calls -to accept to identify this particular source, which is -useful if you're listening on multiple addresses and do -different things depending on what address is connected to. - -If successful and @effective_address is non-%NULL then it will -be set to the address that the binding actually occurred at. This -is helpful for determining the port number that was used for when -requesting a binding to port 0 (ie: "any port"). This address, if -requested, belongs to the caller and must be freed. - -Call g_socket_listener_close() to stop listening on @address; this will not -be done automatically when you drop your final reference to @listener, as -references may be held internally. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocketListener - - - - a #GSocketAddress - - - - a #GSocketType - - - - a #GSocketProtocol - - - - Optional #GObject identifying this source - - - - location to store the address that was bound to, or %NULL. - - - - - - Listens for TCP connections on any available port number for both -IPv6 and IPv4 (if each is available). - -This is useful if you need to have a socket for incoming connections -but don't care about the specific port number. - -@source_object will be passed out in the various calls -to accept to identify this particular source, which is -useful if you're listening on multiple addresses and do -different things depending on what address is connected to. - - - the port number, or 0 in case of failure. - - - - - a #GSocketListener - - - - Optional #GObject identifying this source - - - - - - Helper function for g_socket_listener_add_address() that -creates a TCP/IP socket listening on IPv4 and IPv6 (if -supported) on the specified port on all interfaces. - -@source_object will be passed out in the various calls -to accept to identify this particular source, which is -useful if you're listening on multiple addresses and do -different things depending on what address is connected to. - -Call g_socket_listener_close() to stop listening on @port; this will not -be done automatically when you drop your final reference to @listener, as -references may be held internally. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocketListener - - - - an IP port number (non-zero) - - - - Optional #GObject identifying this source - - - - - - Adds @socket to the set of sockets that we try to accept -new clients from. The socket must be bound to a local -address and listened to. - -@source_object will be passed out in the various calls -to accept to identify this particular source, which is -useful if you're listening on multiple addresses and do -different things depending on what address is connected to. - -The @socket will not be automatically closed when the @listener is finalized -unless the listener held the final reference to the socket. Before GLib 2.42, -the @socket was automatically closed on finalization of the @listener, even -if references to it were held elsewhere. - - - %TRUE on success, %FALSE on error. - - - - - a #GSocketListener - - - - a listening #GSocket - - - - Optional #GObject identifying this source - - - - - - Closes all the sockets in the listener. - - - - - - - a #GSocketListener - - - - - - Sets the listen backlog on the sockets in the listener. This must be called -before adding any sockets, addresses or ports to the #GSocketListener (for -example, by calling g_socket_listener_add_inet_port()) to be effective. - -See g_socket_set_listen_backlog() for details - - - - - - - a #GSocketListener - - - - an integer - - - - - - - - - - - - - - - Emitted when @listener's activity on @socket changes state. -Note that when @listener is used to listen on both IPv4 and -IPv6, a separate set of signals will be emitted for each, and -the order they happen in is undefined. - - - - - - the event that is occurring - - - - the #GSocket the event is occurring on - - - - - - - Class structure for #GSocketListener. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Describes an event occurring on a #GSocketListener. See the -#GSocketListener::event signal for more details. - -Additional values may be added to this type in the future. - - The listener is about to bind a socket. - - - The listener has bound a socket. - - - The listener is about to start - listening on this socket. - - - The listener is now listening on - this socket. - - - - - - - Flags used in g_socket_receive_message() and g_socket_send_message(). -The flags listed in the enum are some commonly available flags, but the -values used for them are the same as on the platform, and any other flags -are passed in/out as is. So to use a platform specific flag, just include -the right system header and pass in the flag. - - No flags. - - - Request to send/receive out of band data. - - - Read data from the socket without removing it from - the queue. - - - Don't use a gateway to send out the packet, - only send to hosts on directly connected networks. - - - - - - - A protocol identifier is specified when creating a #GSocket, which is a -family/type specific identifier, where 0 means the default protocol for -the particular family/type. - -This enum contains a set of commonly available and used protocols. You -can also pass any other identifiers handled by the platform in order to -use protocols not listed here. - - The protocol type is unknown - - - The default protocol for the family/type - - - TCP over IP - - - UDP over IP - - - SCTP over IP - - - - A #GSocketService is an object that represents a service that -is provided to the network or over local sockets. When a new -connection is made to the service the #GSocketService::incoming -signal is emitted. - -A #GSocketService is a subclass of #GSocketListener and you need -to add the addresses you want to accept connections on with the -#GSocketListener APIs. - -There are two options for implementing a network service based on -#GSocketService. The first is to create the service using -g_socket_service_new() and to connect to the #GSocketService::incoming -signal. The second is to subclass #GSocketService and override the -default signal handler implementation. - -In either case, the handler must immediately return, or else it -will block additional incoming connections from being serviced. -If you are interested in writing connection handlers that contain -blocking code then see #GThreadedSocketService. - -The socket service runs on the main loop of the -[thread-default context][g-main-context-push-thread-default-context] -of the thread it is created in, and is not -threadsafe in general. However, the calls to start and stop the -service are thread-safe so these can be used from threads that -handle incoming clients. - - - Creates a new #GSocketService with no sockets to listen for. -New listeners can be added with e.g. g_socket_listener_add_address() -or g_socket_listener_add_inet_port(). - -New services are created active, there is no need to call -g_socket_service_start(), unless g_socket_service_stop() has been -called before. - - - a new #GSocketService. - - - - - - - - - - - - - - - - - - - - - - Check whether the service is active or not. An active -service will accept new clients that connect, while -a non-active service will let connecting clients queue -up until the service is started. - - - %TRUE if the service is active, %FALSE otherwise - - - - - a #GSocketService - - - - - - Restarts the service, i.e. start accepting connections -from the added sockets when the mainloop runs. This only needs -to be called after the service has been stopped from -g_socket_service_stop(). - -This call is thread-safe, so it may be called from a thread -handling an incoming client request. - - - - - - - a #GSocketService - - - - - - Stops the service, i.e. stops accepting connections -from the added sockets when the mainloop runs. - -This call is thread-safe, so it may be called from a thread -handling an incoming client request. - -Note that this only stops accepting new connections; it does not -close the listening sockets, and you can call -g_socket_service_start() again later to begin listening again. To -close the listening sockets, call g_socket_listener_close(). (This -will happen automatically when the #GSocketService is finalized.) - -This must be called before calling g_socket_listener_close() as -the socket service will start accepting connections immediately -when a new socket is added. - - - - - - - a #GSocketService - - - - - - Whether the service is currently accepting connections. - - - - - - - - - - The ::incoming signal is emitted when a new incoming connection -to @service needs to be handled. The handler must initiate the -handling of @connection, but may not block; in essence, -asynchronous operations must be used. - -@connection will be unreffed once the signal handler returns, -so you need to ref it yourself if you are planning to use it. - - %TRUE to stop other handlers from being called - - - - - a new #GSocketConnection object - - - - the source_object passed to - g_socket_listener_add_address() - - - - - - - Class structure for #GSocketService. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This is the function type of the callback used for the #GSource -returned by g_socket_create_source(). - - - it should return %FALSE if the source should be removed. - - - - - the #GSocket - - - - the current condition at the source fired. - - - - data passed in by the user. - - - - - - Flags used when creating a #GSocket. Some protocols may not implement -all the socket types. - - Type unknown or wrong - - - Reliable connection-based byte streams (e.g. TCP). - - - Connectionless, unreliable datagram passing. - (e.g. UDP) - - - Reliable connection-based passing of datagrams - of fixed maximum length (e.g. SCTP). - - - - SRV (service) records are used by some network protocols to provide -service-specific aliasing and load-balancing. For example, XMPP -(Jabber) uses SRV records to locate the XMPP server for a domain; -rather than connecting directly to "example.com" or assuming a -specific server hostname like "xmpp.example.com", an XMPP client -would look up the "xmpp-client" SRV record for "example.com", and -then connect to whatever host was pointed to by that record. - -You can use g_resolver_lookup_service() or -g_resolver_lookup_service_async() to find the #GSrvTargets -for a given service. However, if you are simply planning to connect -to the remote service, you can use #GNetworkService's -#GSocketConnectable interface and not need to worry about -#GSrvTarget at all. - - - Creates a new #GSrvTarget with the given parameters. - -You should not need to use this; normally #GSrvTargets are -created by #GResolver. - - - a new #GSrvTarget. - - - - - the host that the service is running on - - - - the port that the service is running on - - - - the target's priority - - - - the target's weight - - - - - - Copies @target - - - a copy of @target - - - - - a #GSrvTarget - - - - - - Frees @target - - - - - - - a #GSrvTarget - - - - - - Gets @target's hostname (in ASCII form; if you are going to present -this to the user, you should use g_hostname_is_ascii_encoded() to -check if it contains encoded Unicode segments, and use -g_hostname_to_unicode() to convert it if it does.) - - - @target's hostname - - - - - a #GSrvTarget - - - - - - Gets @target's port - - - @target's port - - - - - a #GSrvTarget - - - - - - Gets @target's priority. You should not need to look at this; -#GResolver already sorts the targets according to the algorithm in -RFC 2782. - - - @target's priority - - - - - a #GSrvTarget - - - - - - Gets @target's weight. You should not need to look at this; -#GResolver already sorts the targets according to the algorithm in -RFC 2782. - - - @target's weight - - - - - a #GSrvTarget - - - - - - Sorts @targets in place according to the algorithm in RFC 2782. - - - the head of the sorted list. - - - - - - - a #GList of #GSrvTarget - - - - - - - - - #GStaticResource is an opaque data structure and can only be accessed -using the following functions. - - - - - - - - - - - - - - - - - - Finalized a GResource initialized by g_static_resource_init(). - -This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] -and is not typically used by other code. - - - - - - - pointer to a static #GStaticResource - - - - - - Gets the GResource that was registered by a call to g_static_resource_init(). - -This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] -and is not typically used by other code. - - - a #GResource - - - - - pointer to a static #GStaticResource - - - - - - Initializes a GResource from static data using a -GStaticResource. - -This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] -and is not typically used by other code. - - - - - - - pointer to a static #GStaticResource - - - - - - - #GSubprocess allows the creation of and interaction with child -processes. - -Processes can be communicated with using standard GIO-style APIs (ie: -#GInputStream, #GOutputStream). There are GIO-style APIs to wait for -process termination (ie: cancellable and with an asynchronous -variant). - -There is an API to force a process to terminate, as well as a -race-free API for sending UNIX signals to a subprocess. - -One major advantage that GIO brings over the core GLib library is -comprehensive API for asynchronous I/O, such -g_output_stream_splice_async(). This makes GSubprocess -significantly more powerful and flexible than equivalent APIs in -some other languages such as the `subprocess.py` -included with Python. For example, using #GSubprocess one could -create two child processes, reading standard output from the first, -processing it, and writing to the input stream of the second, all -without blocking the main loop. - -A powerful g_subprocess_communicate() API is provided similar to the -`communicate()` method of `subprocess.py`. This enables very easy -interaction with a subprocess that has been opened with pipes. - -#GSubprocess defaults to tight control over the file descriptors open -in the child process, avoiding dangling-fd issues that are caused by -a simple fork()/exec(). The only open file descriptors in the -spawned process are ones that were explicitly specified by the -#GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was -specified). - -#GSubprocess will quickly reap all child processes as they exit, -avoiding "zombie processes" remaining around for long periods of -time. g_subprocess_wait() can be used to wait for this to happen, -but it will happen even without the call being explicitly made. - -As a matter of principle, #GSubprocess has no API that accepts -shell-style space-separated strings. It will, however, match the -typical shell behaviour of searching the PATH for executables that do -not contain a directory separator in their name. - -#GSubprocess attempts to have a very simple API for most uses (ie: -spawning a subprocess with arguments and support for most typical -kinds of input and output redirection). See g_subprocess_new(). The -#GSubprocessLauncher API is provided for more complicated cases -(advanced types of redirection, environment variable manipulation, -change of working directory, child setup functions, etc). - -A typical use of #GSubprocess will involve calling -g_subprocess_new(), followed by g_subprocess_wait_async() or -g_subprocess_wait(). After the process exits, the status can be -checked using functions such as g_subprocess_get_if_exited() (which -are similar to the familiar WIFEXITED-style POSIX macros). - - - Create a new process with the given flags and varargs argument -list. By default, matching the g_spawn_async() defaults, the -child's stdin will be set to the system null device, and -stdout/stderr will be inherited from the parent. You can use -@flags to control this behavior. - -The argument list must be terminated with %NULL. - - - A newly created #GSubprocess, or %NULL on error (and @error - will be set) - - - - - flags that define the behaviour of the subprocess - - - - return location for an error, or %NULL - - - - first commandline argument to pass to the subprocess - - - - more commandline arguments, followed by %NULL - - - - - - Create a new process with the given flags and argument list. - -The argument list is expected to be %NULL-terminated. - - - A newly created #GSubprocess, or %NULL on error (and @error - will be set) - - - - - commandline arguments for the subprocess - - - - - - flags that define the behaviour of the subprocess - - - - - - Communicate with the subprocess until it terminates, and all input -and output has been completed. - -If @stdin_buf is given, the subprocess must have been created with -%G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the -stdin of the subprocess and the pipe is closed (ie: EOF). - -At the same time (as not to cause blocking when dealing with large -amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or -%G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those -streams. The data that was read is returned in @stdout and/or -the @stderr. - -If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, -@stdout_buf will contain the data read from stdout. Otherwise, for -subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, -@stdout_buf will be set to %NULL. Similar provisions apply to -@stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. - -As usual, any output variable may be given as %NULL to ignore it. - -If you desire the stdout and stderr data to be interleaved, create -the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and -%G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned -in @stdout_buf and @stderr_buf will be set to %NULL. - -In case of any error (including cancellation), %FALSE will be -returned with @error set. Some or all of the stdin data may have -been written. Any stdout or stderr data that has been read will be -discarded. None of the out variables (aside from @error) will have -been set to anything in particular and should not be inspected. - -In the case that %TRUE is returned, the subprocess has exited and the -exit status inspection APIs (eg: g_subprocess_get_if_exited(), -g_subprocess_get_exit_status()) may be used. - -You should not attempt to use any of the subprocess pipes after -starting this function, since they may be left in strange states, -even if the operation was cancelled. You should especially not -attempt to interact with the pipes while the operation is in progress -(either from another thread or if using the asynchronous version). - - - %TRUE if successful - - - - - a #GSubprocess - - - - data to send to the stdin of the subprocess, or %NULL - - - - a #GCancellable - - - - data read from the subprocess stdout - - - - data read from the subprocess stderr - - - - - - Asynchronous version of g_subprocess_communicate(). Complete -invocation with g_subprocess_communicate_finish(). - - - - - - - Self - - - - Input data, or %NULL - - - - Cancellable - - - - Callback - - - - User data - - - - - - Complete an invocation of g_subprocess_communicate_async(). - - - - - - - Self - - - - Result - - - - Return location for stdout data - - - - Return location for stderr data - - - - - - Like g_subprocess_communicate(), but validates the output of the -process as UTF-8, and returns it as a regular NUL terminated string. - -On error, @stdout_buf and @stderr_buf will be set to undefined values and -should not be used. - - - - - - - a #GSubprocess - - - - data to send to the stdin of the subprocess, or %NULL - - - - a #GCancellable - - - - data read from the subprocess stdout - - - - data read from the subprocess stderr - - - - - - Asynchronous version of g_subprocess_communicate_utf8(). Complete -invocation with g_subprocess_communicate_utf8_finish(). - - - - - - - Self - - - - Input data, or %NULL - - - - Cancellable - - - - Callback - - - - User data - - - - - - Complete an invocation of g_subprocess_communicate_utf8_async(). - - - - - - - Self - - - - Result - - - - Return location for stdout data - - - - Return location for stderr data - - - - - - Use an operating-system specific method to attempt an immediate, -forceful termination of the process. There is no mechanism to -determine whether or not the request itself was successful; -however, you can use g_subprocess_wait() to monitor the status of -the process after calling this function. - -On Unix, this function sends %SIGKILL. - - - - - - - a #GSubprocess - - - - - - Check the exit status of the subprocess, given that it exited -normally. This is the value passed to the exit() system call or the -return value from main. - -This is equivalent to the system WEXITSTATUS macro. - -It is an error to call this function before g_subprocess_wait() and -unless g_subprocess_get_if_exited() returned %TRUE. - - - the exit status - - - - - a #GSubprocess - - - - - - On UNIX, returns the process ID as a decimal string. -On Windows, returns the result of GetProcessId() also as a string. -If the subprocess has terminated, this will return %NULL. - - - the subprocess identifier, or %NULL if the subprocess - has terminated - - - - - a #GSubprocess - - - - - - Check if the given subprocess exited normally (ie: by way of exit() -or return from main()). - -This is equivalent to the system WIFEXITED macro. - -It is an error to call this function before g_subprocess_wait() has -returned. - - - %TRUE if the case of a normal exit - - - - - a #GSubprocess - - - - - - Check if the given subprocess terminated in response to a signal. - -This is equivalent to the system WIFSIGNALED macro. - -It is an error to call this function before g_subprocess_wait() has -returned. - - - %TRUE if the case of termination due to a signal - - - - - a #GSubprocess - - - - - - Gets the raw status code of the process, as from waitpid(). - -This value has no particular meaning, but it can be used with the -macros defined by the system headers such as WIFEXITED. It can also -be used with g_spawn_check_exit_status(). - -It is more likely that you want to use g_subprocess_get_if_exited() -followed by g_subprocess_get_exit_status(). - -It is an error to call this function before g_subprocess_wait() has -returned. - - - the (meaningless) waitpid() exit status from the kernel - - - - - a #GSubprocess - - - - - - Gets the #GInputStream from which to read the stderr output of -@subprocess. - -The process must have been created with -%G_SUBPROCESS_FLAGS_STDERR_PIPE. - - - the stderr pipe - - - - - a #GSubprocess - - - - - - Gets the #GOutputStream that you can write to in order to give data -to the stdin of @subprocess. - -The process must have been created with -%G_SUBPROCESS_FLAGS_STDIN_PIPE. - - - the stdout pipe - - - - - a #GSubprocess - - - - - - Gets the #GInputStream from which to read the stdout output of -@subprocess. - -The process must have been created with -%G_SUBPROCESS_FLAGS_STDOUT_PIPE. - - - the stdout pipe - - - - - a #GSubprocess - - - - - - Checks if the process was "successful". A process is considered -successful if it exited cleanly with an exit status of 0, either by -way of the exit() system call or return from main(). - -It is an error to call this function before g_subprocess_wait() has -returned. - - - %TRUE if the process exited cleanly with a exit status of 0 - - - - - a #GSubprocess - - - - - - Get the signal number that caused the subprocess to terminate, given -that it terminated due to a signal. - -This is equivalent to the system WTERMSIG macro. - -It is an error to call this function before g_subprocess_wait() and -unless g_subprocess_get_if_signaled() returned %TRUE. - - - the signal causing termination - - - - - a #GSubprocess - - - - - - Sends the UNIX signal @signal_num to the subprocess, if it is still -running. - -This API is race-free. If the subprocess has terminated, it will not -be signalled. - -This API is not available on Windows. - - - - - - - a #GSubprocess - - - - the signal number to send - - - - - - Synchronously wait for the subprocess to terminate. - -After the process terminates you can query its exit status with -functions such as g_subprocess_get_if_exited() and -g_subprocess_get_exit_status(). - -This function does not fail in the case of the subprocess having -abnormal termination. See g_subprocess_wait_check() for that. - -Cancelling @cancellable doesn't kill the subprocess. Call -g_subprocess_force_exit() if it is desirable. - - - %TRUE on success, %FALSE if @cancellable was cancelled - - - - - a #GSubprocess - - - - a #GCancellable - - - - - - Wait for the subprocess to terminate. - -This is the asynchronous version of g_subprocess_wait(). - - - - - - - a #GSubprocess - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback to call when the operation is complete - - - - user_data for @callback - - - - - - Combines g_subprocess_wait() with g_spawn_check_exit_status(). - - - %TRUE on success, %FALSE if process exited abnormally, or -@cancellable was cancelled - - - - - a #GSubprocess - - - - a #GCancellable - - - - - - Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). - -This is the asynchronous version of g_subprocess_wait_check(). - - - - - - - a #GSubprocess - - - - a #GCancellable, or %NULL - - - - a #GAsyncReadyCallback to call when the operation is complete - - - - user_data for @callback - - - - - - Collects the result of a previous call to -g_subprocess_wait_check_async(). - - - %TRUE if successful, or %FALSE with @error set - - - - - a #GSubprocess - - - - the #GAsyncResult passed to your #GAsyncReadyCallback - - - - - - Collects the result of a previous call to -g_subprocess_wait_async(). - - - %TRUE if successful, or %FALSE with @error set - - - - - a #GSubprocess - - - - the #GAsyncResult passed to your #GAsyncReadyCallback - - - - - - - - - - - - - - - Flags to define the behaviour of a #GSubprocess. - -Note that the default for stdin is to redirect from `/dev/null`. For -stdout and stderr the default are for them to inherit the -corresponding descriptor from the calling process. - -Note that it is a programmer error to mix 'incompatible' flags. For -example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and -%G_SUBPROCESS_FLAGS_STDOUT_SILENCE. - - No flags. - - - create a pipe for the stdin of the - spawned process that can be accessed with - g_subprocess_get_stdin_pipe(). - - - stdin is inherited from the - calling process. - - - create a pipe for the stdout of the - spawned process that can be accessed with - g_subprocess_get_stdout_pipe(). - - - silence the stdout of the spawned - process (ie: redirect to `/dev/null`). - - - create a pipe for the stderr of the - spawned process that can be accessed with - g_subprocess_get_stderr_pipe(). - - - silence the stderr of the spawned - process (ie: redirect to `/dev/null`). - - - merge the stderr of the spawned - process with whatever the stdout happens to be. This is a good way - of directing both streams to a common log file, for example. - - - spawned processes will inherit the - file descriptors of their parent, unless those descriptors have - been explicitly marked as close-on-exec. This flag has no effect - over the "standard" file descriptors (stdin, stdout, stderr). - - - - This class contains a set of options for launching child processes, -such as where its standard input and output will be directed, the -argument list, the environment, and more. - -While the #GSubprocess class has high level functions covering -popular cases, use of this class allows access to more advanced -options. It can also be used to launch multiple subprocesses with -a similar configuration. - - Creates a new #GSubprocessLauncher. - -The launcher is created with the default options. A copy of the -environment of the calling process is made at the time of this call -and will be used as the environment that the process is launched in. - - - - - - - #GSubprocessFlags - - - - - - Returns the value of the environment variable @variable in the -environment of processes launched from this launcher. - -On UNIX, the returned string can be an arbitrary byte string. -On Windows, it will be UTF-8. - - - the value of the environment variable, - %NULL if unset - - - - - a #GSubprocessLauncher - - - - the environment variable to get - - - - - - Sets up a child setup function. - -The child setup function will be called after fork() but before -exec() on the child's side. - -@destroy_notify will not be automatically called on the child's side -of the fork(). It will only be called when the last reference on the -#GSubprocessLauncher is dropped or when a new child setup function is -given. - -%NULL can be given as @child_setup to disable the functionality. - -Child setup functions are only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a #GSpawnChildSetupFunc to use as the child setup function - - - - user data for @child_setup - - - - a #GDestroyNotify for @user_data - - - - - - Sets the current working directory that processes will be launched -with. - -By default processes are launched with the current working directory -of the launching process at the time of launch. - - - - - - - a #GSubprocessLauncher - - - - the cwd for launched processes - - - - - - Replace the entire environment of processes launched from this -launcher with the given 'environ' variable. - -Typically you will build this variable by using g_listenv() to copy -the process 'environ' and using the functions g_environ_setenv(), -g_environ_unsetenv(), etc. - -As an alternative, you can use g_subprocess_launcher_setenv(), -g_subprocess_launcher_unsetenv(), etc. - -Pass an empty array to set an empty environment. Pass %NULL to inherit the -parent process’ environment. As of GLib 2.54, the parent process’ environment -will be copied when g_subprocess_launcher_set_environ() is called. -Previously, it was copied when the subprocess was executed. This means the -copied environment may now be modified (using g_subprocess_launcher_setenv(), -etc.) before launching the subprocess. - -On UNIX, all strings in this array can be arbitrary byte strings. -On Windows, they should be in UTF-8. - - - - - - - a #GSubprocessLauncher - - - - - the replacement environment - - - - - - - - Sets the flags on the launcher. - -The default flags are %G_SUBPROCESS_FLAGS_NONE. - -You may not set flags that specify conflicting options for how to -handle a particular stdio stream (eg: specifying both -%G_SUBPROCESS_FLAGS_STDIN_PIPE and -%G_SUBPROCESS_FLAGS_STDIN_INHERIT). - -You may also not set a flag that conflicts with a previous call to a -function like g_subprocess_launcher_set_stdin_file_path() or -g_subprocess_launcher_take_stdout_fd(). - - - - - - - a #GSubprocessLauncher - - - - #GSubprocessFlags - - - - - - Sets the file path to use as the stderr for spawned processes. - -If @path is %NULL then any previously given path is unset. - -The file will be created or truncated when the process is spawned, as -would be the case if using '2>' at the shell. - -If you want to send both stdout and stderr to the same file then use -%G_SUBPROCESS_FLAGS_STDERR_MERGE. - -You may not set a stderr file path if a stderr fd is already set or -if the launcher flags contain any flags directing stderr elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a filename or %NULL - - - - - - Sets the file path to use as the stdin for spawned processes. - -If @path is %NULL then any previously given path is unset. - -The file must exist or spawning the process will fail. - -You may not set a stdin file path if a stdin fd is already set or if -the launcher flags contain any flags directing stdin elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - - - - - - Sets the file path to use as the stdout for spawned processes. - -If @path is %NULL then any previously given path is unset. - -The file will be created or truncated when the process is spawned, as -would be the case if using '>' at the shell. - -You may not set a stdout file path if a stdout fd is already set or -if the launcher flags contain any flags directing stdout elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a filename or %NULL - - - - - - Sets the environment variable @variable in the environment of -processes launched from this launcher. - -On UNIX, both the variable's name and value can be arbitrary byte -strings, except that the variable's name cannot contain '='. -On Windows, they should be in UTF-8. - - - - - - - a #GSubprocessLauncher - - - - the environment variable to set, - must not contain '=' - - - - the new value for the variable - - - - whether to change the variable if it already exists - - - - - - Creates a #GSubprocess given a provided varargs list of arguments. - - - A new #GSubprocess, or %NULL on error (and @error will be set) - - - - - a #GSubprocessLauncher - - - - Error - - - - Command line arguments - - - - Continued arguments, %NULL terminated - - - - - - Creates a #GSubprocess given a provided array of arguments. - - - A new #GSubprocess, or %NULL on error (and @error will be set) - - - - - a #GSubprocessLauncher - - - - Command line arguments - - - - - - - - Transfer an arbitrary file descriptor from parent process to the -child. This function takes "ownership" of the fd; it will be closed -in the parent when @self is freed. - -By default, all file descriptors from the parent will be closed. -This function allows you to create (for example) a custom pipe() or -socketpair() before launching the process, and choose the target -descriptor in the child. - -An example use case is GNUPG, which has a command line argument ---passphrase-fd providing a file descriptor number where it expects -the passphrase to be written. - - - - - - - a #GSubprocessLauncher - - - - File descriptor in parent process - - - - Target descriptor for child process - - - - - - Sets the file descriptor to use as the stderr for spawned processes. - -If @fd is -1 then any previously given fd is unset. - -Note that the default behaviour is to pass stderr through to the -stderr of the parent process. - -The passed @fd belongs to the #GSubprocessLauncher. It will be -automatically closed when the launcher is finalized. The file -descriptor will also be closed on the child side when executing the -spawned process. - -You may not set a stderr fd if a stderr file path is already set or -if the launcher flags contain any flags directing stderr elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a file descriptor, or -1 - - - - - - Sets the file descriptor to use as the stdin for spawned processes. - -If @fd is -1 then any previously given fd is unset. - -Note that if your intention is to have the stdin of the calling -process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT -is a better way to go about doing that. - -The passed @fd is noted but will not be touched in the current -process. It is therefore necessary that it be kept open by the -caller until the subprocess is spawned. The file descriptor will -also not be explicitly closed on the child side, so it must be marked -O_CLOEXEC if that's what you want. - -You may not set a stdin fd if a stdin file path is already set or if -the launcher flags contain any flags directing stdin elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a file descriptor, or -1 - - - - - - Sets the file descriptor to use as the stdout for spawned processes. - -If @fd is -1 then any previously given fd is unset. - -Note that the default behaviour is to pass stdout through to the -stdout of the parent process. - -The passed @fd is noted but will not be touched in the current -process. It is therefore necessary that it be kept open by the -caller until the subprocess is spawned. The file descriptor will -also not be explicitly closed on the child side, so it must be marked -O_CLOEXEC if that's what you want. - -You may not set a stdout fd if a stdout file path is already set or -if the launcher flags contain any flags directing stdout elsewhere. - -This feature is only available on UNIX. - - - - - - - a #GSubprocessLauncher - - - - a file descriptor, or -1 - - - - - - Removes the environment variable @variable from the environment of -processes launched from this launcher. - -On UNIX, the variable's name can be an arbitrary byte string not -containing '='. On Windows, it should be in UTF-8. - - - - - - - a #GSubprocessLauncher - - - - the environment variable to unset, - must not contain '=' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extension point for TLS functionality via #GTlsBackend. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The purpose used to verify the client certificate in a TLS connection. -Used by TLS servers. - - - - - The purpose used to verify the server certificate in a TLS connection. This -is the most common purpose in use. Used by TLS clients. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GTask represents and manages a cancellable "task". - -## Asynchronous operations - -The most common usage of #GTask is as a #GAsyncResult, to -manage data during an asynchronous operation. You call -g_task_new() in the "start" method, followed by -g_task_set_task_data() and the like if you need to keep some -additional data associated with the task, and then pass the -task object around through your asynchronous operation. -Eventually, you will call a method such as -g_task_return_pointer() or g_task_return_error(), which will -save the value you give it and then invoke the task's callback -function in the -[thread-default main context][g-main-context-push-thread-default] -where it was created (waiting until the next iteration of the main -loop first, if necessary). The caller will pass the #GTask back to -the operation's finish function (as a #GAsyncResult), and you can -use g_task_propagate_pointer() or the like to extract the -return value. - -Here is an example for using GTask as a GAsyncResult: -|[<!-- language="C" --> - typedef struct { - CakeFrostingType frosting; - char *message; - } DecorationData; - - static void - decoration_data_free (DecorationData *decoration) - { - g_free (decoration->message); - g_slice_free (DecorationData, decoration); - } - - static void - baked_cb (Cake *cake, - gpointer user_data) - { - GTask *task = user_data; - DecorationData *decoration = g_task_get_task_data (task); - GError *error = NULL; - - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } - - if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) - { - g_object_unref (cake); - // g_task_return_error() takes ownership of error - g_task_return_error (task, error); - g_object_unref (task); - return; - } - - g_task_return_pointer (task, cake, g_object_unref); - g_object_unref (task); - } - - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - GTask *task; - DecorationData *decoration; - Cake *cake; - - task = g_task_new (self, cancellable, callback, user_data); - if (radius < 3) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, - "%ucm radius cakes are silly", - radius); - g_object_unref (task); - return; - } - - cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); - if (cake != NULL) - { - // _baker_get_cached_cake() returns a reffed cake - g_task_return_pointer (task, cake, g_object_unref); - g_object_unref (task); - return; - } - - decoration = g_slice_new (DecorationData); - decoration->frosting = frosting; - decoration->message = g_strdup (message); - g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); - - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } - - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); - - return g_task_propagate_pointer (G_TASK (result), error); - } -]| - -## Chained asynchronous operations - -#GTask also tries to simplify asynchronous operations that -internally chain together several smaller asynchronous -operations. g_task_get_cancellable(), g_task_get_context(), -and g_task_get_priority() allow you to get back the task's -#GCancellable, #GMainContext, and [I/O priority][io-priority] -when starting a new subtask, so you don't have to keep track -of them yourself. g_task_attach_source() simplifies the case -of waiting for a source to fire (automatically using the correct -#GMainContext and priority). - -Here is an example for chained asynchronous operations: - |[<!-- language="C" --> - typedef struct { - Cake *cake; - CakeFrostingType frosting; - char *message; - } BakingData; - - static void - decoration_data_free (BakingData *bd) - { - if (bd->cake) - g_object_unref (bd->cake); - g_free (bd->message); - g_slice_free (BakingData, bd); - } - - static void - decorated_cb (Cake *cake, - GAsyncResult *result, - gpointer user_data) - { - GTask *task = user_data; - GError *error = NULL; - - if (!cake_decorate_finish (cake, result, &error)) - { - g_object_unref (cake); - g_task_return_error (task, error); - g_object_unref (task); - return; - } - - // baking_data_free() will drop its ref on the cake, so we have to - // take another here to give to the caller. - g_task_return_pointer (task, g_object_ref (cake), g_object_unref); - g_object_unref (task); - } - - static gboolean - decorator_ready (gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - - cake_decorate_async (bd->cake, bd->frosting, bd->message, - g_task_get_cancellable (task), - decorated_cb, task); - - return G_SOURCE_REMOVE; - } - - static void - baked_cb (Cake *cake, - gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - GError *error = NULL; - - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } - - bd->cake = cake; - - // Bail out now if the user has already cancelled - if (g_task_return_error_if_cancelled (task)) - { - g_object_unref (task); - return; - } - - if (cake_decorator_available (cake)) - decorator_ready (task); - else - { - GSource *source; - - source = cake_decorator_wait_source_new (cake); - // Attach @source to @task's GMainContext and have it call - // decorator_ready() when it is ready. - g_task_attach_source (task, source, decorator_ready); - g_source_unref (source); - } - } - - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - gint priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - GTask *task; - BakingData *bd; - - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_priority (task, priority); - - bd = g_slice_new0 (BakingData); - bd->frosting = frosting; - bd->message = g_strdup (message); - g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); - - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } - - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); - - return g_task_propagate_pointer (G_TASK (result), error); - } -]| - -## Asynchronous operations from synchronous ones - -You can use g_task_run_in_thread() to turn a synchronous -operation into an asynchronous one, by running it in a thread. -When it completes, the result will be dispatched to the -[thread-default main context][g-main-context-push-thread-default] -where the #GTask was created. - -Running a task in a thread: - |[<!-- language="C" --> - typedef struct { - guint radius; - CakeFlavor flavor; - CakeFrostingType frosting; - char *message; - } CakeData; - - static void - cake_data_free (CakeData *cake_data) - { - g_free (cake_data->message); - g_slice_free (CakeData, cake_data); - } - - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) - { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - cancellable, &error); - if (cake) - g_task_return_pointer (task, cake, g_object_unref); - else - g_task_return_error (task, error); - } - - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - CakeData *cake_data; - GTask *task; - - cake_data = g_slice_new (CakeData); - cake_data->radius = radius; - cake_data->flavor = flavor; - cake_data->frosting = frosting; - cake_data->message = g_strdup (message); - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_run_in_thread (task, bake_cake_thread); - g_object_unref (task); - } - - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); - - return g_task_propagate_pointer (G_TASK (result), error); - } -]| - -## Adding cancellability to uncancellable tasks - -Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() -can be used to turn an uncancellable operation into a -cancellable one. If you call g_task_set_return_on_cancel(), -passing %TRUE, then if the task's #GCancellable is cancelled, -it will return control back to the caller immediately, while -allowing the task thread to continue running in the background -(and simply discarding its result when it finally does finish). -Provided that the task thread is careful about how it uses -locks and other externally-visible resources, this allows you -to make "GLib-friendly" asynchronous and cancellable -synchronous variants of blocking APIs. - -Cancelling a task: - |[<!-- language="C" --> - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) - { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - &error); - if (error) - { - g_task_return_error (task, error); - return; - } - - // If the task has already been cancelled, then we don't want to add - // the cake to the cake cache. Likewise, we don't want to have the - // task get cancelled in the middle of updating the cache. - // g_task_set_return_on_cancel() will return %TRUE here if it managed - // to disable return-on-cancel, or %FALSE if the task was cancelled - // before it could. - if (g_task_set_return_on_cancel (task, FALSE)) - { - // If the caller cancels at this point, their - // GAsyncReadyCallback won't be invoked until we return, - // so we don't have to worry that this code will run at - // the same time as that code does. But if there were - // other functions that might look at the cake cache, - // then we'd probably need a GMutex here as well. - baker_add_cake_to_cache (baker, cake); - g_task_return_pointer (task, cake, g_object_unref); - } - } - - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - CakeData *cake_data; - GTask *task; - - cake_data = g_slice_new (CakeData); - - ... - - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread (task, bake_cake_thread); - } - - Cake * - baker_bake_cake_sync (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GError **error) - { - CakeData *cake_data; - GTask *task; - Cake *cake; - - cake_data = g_slice_new (CakeData); - - ... - - task = g_task_new (self, cancellable, NULL, NULL); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread_sync (task, bake_cake_thread); - - cake = g_task_propagate_pointer (task, error); - g_object_unref (task); - return cake; - } -]| - -## Porting from GSimpleAsyncResult - -#GTask's API attempts to be simpler than #GSimpleAsyncResult's -in several ways: -- You can save task-specific data with g_task_set_task_data(), and - retrieve it later with g_task_get_task_data(). This replaces the - abuse of g_simple_async_result_set_op_res_gpointer() for the same - purpose with #GSimpleAsyncResult. -- In addition to the task data, #GTask also keeps track of the - [priority][io-priority], #GCancellable, and - #GMainContext associated with the task, so tasks that consist of - a chain of simpler asynchronous operations will have easy access - to those values when starting each sub-task. -- g_task_return_error_if_cancelled() provides simplified - handling for cancellation. In addition, cancellation - overrides any other #GTask return value by default, like - #GSimpleAsyncResult does when - g_simple_async_result_set_check_cancellable() is called. - (You can use g_task_set_check_cancellable() to turn off that - behavior.) On the other hand, g_task_run_in_thread() - guarantees that it will always run your - `task_func`, even if the task's #GCancellable - is already cancelled before the task gets a chance to run; - you can start your `task_func` with a - g_task_return_error_if_cancelled() check if you need the - old behavior. -- The "return" methods (eg, g_task_return_pointer()) - automatically cause the task to be "completed" as well, and - there is no need to worry about the "complete" vs "complete - in idle" distinction. (#GTask automatically figures out - whether the task's callback can be invoked directly, or - if it needs to be sent to another #GMainContext, or delayed - until the next iteration of the current #GMainContext.) -- The "finish" functions for #GTask based operations are generally - much simpler than #GSimpleAsyncResult ones, normally consisting - of only a single call to g_task_propagate_pointer() or the like. - Since g_task_propagate_pointer() "steals" the return value from - the #GTask, it is not necessary to juggle pointers around to - prevent it from being freed twice. -- With #GSimpleAsyncResult, it was common to call - g_simple_async_result_propagate_error() from the - `_finish()` wrapper function, and have - virtual method implementations only deal with successful - returns. This behavior is deprecated, because it makes it - difficult for a subclass to chain to a parent class's async - methods. Instead, the wrapper function should just be a - simple wrapper, and the virtual method should call an - appropriate `g_task_propagate_` function. - Note that wrapper methods can now use - g_async_result_legacy_propagate_error() to do old-style - #GSimpleAsyncResult error-returning behavior, and - g_async_result_is_tagged() to check if a result is tagged as - having come from the `_async()` wrapper - function (for "short-circuit" results, such as when passing - 0 to g_input_stream_read_async()). - - - - Creates a #GTask acting on @source_object, which will eventually be -used to invoke @callback in the current -[thread-default main context][g-main-context-push-thread-default]. - -Call this in the "start" method of your asynchronous method, and -pass the #GTask around throughout the asynchronous operation. You -can use g_task_set_task_data() to attach task-specific data to the -object, which you can retrieve later via g_task_get_task_data(). - -By default, if @cancellable is cancelled, then the return value of -the task will always be %G_IO_ERROR_CANCELLED, even if the task had -already completed before the cancellation. This allows for -simplified handling in cases where cancellation may imply that -other objects that the task depends on have been destroyed. If you -do not want this behavior, you can use -g_task_set_check_cancellable() to change it. - - - a #GTask. - - - - - the #GObject that owns - this task, or %NULL. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - - - Checks that @result is a #GTask, and that @source_object is its -source object (or that @source_object is %NULL and @result has no -source object). This can be used in g_return_if_fail() checks. - - - %TRUE if @result and @source_object are valid, %FALSE -if not - - - - - A #GAsyncResult - - - - the source object - expected to be associated with the task - - - - - - Creates a #GTask and then immediately calls g_task_return_error() -on it. Use this in the wrapper function of an asynchronous method -when you want to avoid even calling the virtual method. You can -then use g_async_result_is_tagged() in the finish method wrapper to -check if the result there is tagged as having been created by the -wrapper method, and deal with it appropriately if so. - -See also g_task_report_new_error(). - - - - - - - the #GObject that owns - this task, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - an opaque pointer indicating the source of this task - - - - error to report - - - - - - Creates a #GTask and then immediately calls -g_task_return_new_error() on it. Use this in the wrapper function -of an asynchronous method when you want to avoid even calling the -virtual method. You can then use g_async_result_is_tagged() in the -finish method wrapper to check if the result there is tagged as -having been created by the wrapper method, and deal with it -appropriately if so. - -See also g_task_report_error(). - - - - - - - the #GObject that owns - this task, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - an opaque pointer indicating the source of this task - - - - a #GQuark. - - - - an error code. - - - - a string with format characters. - - - - a list of values to insert into @format. - - - - - - A utility function for dealing with async operations where you need -to wait for a #GSource to trigger. Attaches @source to @task's -#GMainContext with @task's [priority][io-priority], and sets @source's -callback to @callback, with @task as the callback's `user_data`. - -It will set the @source’s name to the task’s name (as set with -g_task_set_name()), if one has been set. - -This takes a reference on @task until @source is destroyed. - - - - - - - a #GTask - - - - the source to attach - - - - the callback to invoke when @source triggers - - - - - - Gets @task's #GCancellable - - - @task's #GCancellable - - - - - a #GTask - - - - - - Gets @task's check-cancellable flag. See -g_task_set_check_cancellable() for more details. - - - - - - - the #GTask - - - - - - Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after -the task’s callback is invoked, and will return %FALSE if called from inside -the callback. - - - %TRUE if the task has completed, %FALSE otherwise. - - - - - a #GTask. - - - - - - Gets the #GMainContext that @task will return its result in (that -is, the context that was the -[thread-default main context][g-main-context-push-thread-default] -at the point when @task was created). - -This will always return a non-%NULL value, even if the task's -context is the default #GMainContext. - - - @task's #GMainContext - - - - - a #GTask - - - - - - Gets @task’s name. See g_task_set_name(). - - - @task’s name, or %NULL - - - - - a #GTask - - - - - - Gets @task's priority - - - @task's priority - - - - - a #GTask - - - - - - Gets @task's return-on-cancel flag. See -g_task_set_return_on_cancel() for more details. - - - - - - - the #GTask - - - - - - Gets the source object from @task. Like -g_async_result_get_source_object(), but does not ref the object. - - - @task's source object, or %NULL - - - - - a #GTask - - - - - - Gets @task's source tag. See g_task_set_source_tag(). - - - @task's source tag - - - - - a #GTask - - - - - - Gets @task's `task_data`. - - - @task's `task_data`. - - - - - a #GTask - - - - - - Tests if @task resulted in an error. - - - %TRUE if the task resulted in an error, %FALSE otherwise. - - - - - a #GTask. - - - - - - Gets the result of @task as a #gboolean. - -If the task resulted in an error, or was cancelled, then this will -instead return %FALSE and set @error. - -Since this method transfers ownership of the return value (or -error) to the caller, you may only call it once. - - - the task result, or %FALSE on error - - - - - a #GTask. - - - - - - Gets the result of @task as an integer (#gssize). - -If the task resulted in an error, or was cancelled, then this will -instead return -1 and set @error. - -Since this method transfers ownership of the return value (or -error) to the caller, you may only call it once. - - - the task result, or -1 on error - - - - - a #GTask. - - - - - - Gets the result of @task as a pointer, and transfers ownership -of that value to the caller. - -If the task resulted in an error, or was cancelled, then this will -instead return %NULL and set @error. - -Since this method transfers ownership of the return value (or -error) to the caller, you may only call it once. - - - the task result, or %NULL on error - - - - - a #GTask - - - - - - Gets the result of @task as a #GValue, and transfers ownership of -that value to the caller. As with g_task_return_value(), this is -a generic low-level method; g_task_propagate_pointer() and the like -will usually be more useful for C code. - -If the task resulted in an error, or was cancelled, then this will -instead set @error and return %FALSE. - -Since this method transfers ownership of the return value (or -error) to the caller, you may only call it once. - - - %TRUE if @task succeeded, %FALSE on error. - - - - - a #GTask - - - - return location for the #GValue - - - - - - Sets @task's result to @result and completes the task (see -g_task_return_pointer() for more discussion of exactly what this -means). - - - - - - - a #GTask. - - - - the #gboolean result of a task function. - - - - - - Sets @task's result to @error (which @task assumes ownership of) -and completes the task (see g_task_return_pointer() for more -discussion of exactly what this means). - -Note that since the task takes ownership of @error, and since the -task may be completed before returning from g_task_return_error(), -you cannot assume that @error is still valid after calling this. -Call g_error_copy() on the error if you need to keep a local copy -as well. - -See also g_task_return_new_error(). - - - - - - - a #GTask. - - - - the #GError result of a task function. - - - - - - Checks if @task's #GCancellable has been cancelled, and if so, sets -@task's error accordingly and completes the task (see -g_task_return_pointer() for more discussion of exactly what this -means). - - - %TRUE if @task has been cancelled, %FALSE if not - - - - - a #GTask - - - - - - Sets @task's result to @result and completes the task (see -g_task_return_pointer() for more discussion of exactly what this -means). - - - - - - - a #GTask. - - - - the integer (#gssize) result of a task function. - - - - - - Sets @task's result to a new #GError created from @domain, @code, -@format, and the remaining arguments, and completes the task (see -g_task_return_pointer() for more discussion of exactly what this -means). - -See also g_task_return_error(). - - - - - - - a #GTask. - - - - a #GQuark. - - - - an error code. - - - - a string with format characters. - - - - a list of values to insert into @format. - - - - - - Sets @task's result to @result and completes the task. If @result -is not %NULL, then @result_destroy will be used to free @result if -the caller does not take ownership of it with -g_task_propagate_pointer(). - -"Completes the task" means that for an ordinary asynchronous task -it will either invoke the task's callback, or else queue that -callback to be invoked in the proper #GMainContext, or in the next -iteration of the current #GMainContext. For a task run via -g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this -method will save @result to be returned to the caller later, but -the task will not actually be completed until the #GTaskThreadFunc -exits. - -Note that since the task may be completed before returning from -g_task_return_pointer(), you cannot assume that @result is still -valid after calling this, unless you are still holding another -reference on it. - - - - - - - a #GTask - - - - the pointer result of a task - function - - - - a #GDestroyNotify function. - - - - - - Sets @task's result to @result (by copying it) and completes the task. - -If @result is %NULL then a #GValue of type #G_TYPE_POINTER -with a value of %NULL will be used for the result. - -This is a very generic low-level method intended primarily for use -by language bindings; for C code, g_task_return_pointer() and the -like will normally be much easier to use. - - - - - - - a #GTask - - - - the #GValue result of - a task function - - - - - - Runs @task_func in another thread. When @task_func returns, @task's -#GAsyncReadyCallback will be invoked in @task's #GMainContext. - -This takes a ref on @task until the task completes. - -See #GTaskThreadFunc for more details about how @task_func is handled. - -Although GLib currently rate-limits the tasks queued via -g_task_run_in_thread(), you should not assume that it will always -do this. If you have a very large number of tasks to run, but don't -want them to all run at once, you should only queue a limited -number of them at a time. - - - - - - - a #GTask - - - - a #GTaskThreadFunc - - - - - - Runs @task_func in another thread, and waits for it to return or be -cancelled. You can use g_task_propagate_pointer(), etc, afterward -to get the result of @task_func. - -See #GTaskThreadFunc for more details about how @task_func is handled. - -Normally this is used with tasks created with a %NULL -`callback`, but note that even if the task does -have a callback, it will not be invoked when @task_func returns. -#GTask:completed will be set to %TRUE just before this function returns. - -Although GLib currently rate-limits the tasks queued via -g_task_run_in_thread_sync(), you should not assume that it will -always do this. If you have a very large number of tasks to run, -but don't want them to all run at once, you should only queue a -limited number of them at a time. - - - - - - - a #GTask - - - - a #GTaskThreadFunc - - - - - - Sets or clears @task's check-cancellable flag. If this is %TRUE -(the default), then g_task_propagate_pointer(), etc, and -g_task_had_error() will check the task's #GCancellable first, and -if it has been cancelled, then they will consider the task to have -returned an "Operation was cancelled" error -(%G_IO_ERROR_CANCELLED), regardless of any other error or return -value the task may have had. - -If @check_cancellable is %FALSE, then the #GTask will not check the -cancellable itself, and it is up to @task's owner to do this (eg, -via g_task_return_error_if_cancelled()). - -If you are using g_task_set_return_on_cancel() as well, then -you must leave check-cancellable set %TRUE. - - - - - - - the #GTask - - - - whether #GTask will check the state of - its #GCancellable for you. - - - - - - Sets @task’s name, used in debugging and profiling. The name defaults to -%NULL. - -The task name should describe in a human readable way what the task does. -For example, ‘Open file’ or ‘Connect to network host’. It is used to set the -name of the #GSource used for idle completion of the task. - -This function may only be called before the @task is first used in a thread -other than the one it was constructed in. - - - - - - - a #GTask - - - - a human readable name for the task, or %NULL to unset it - - - - - - Sets @task's priority. If you do not call this, it will default to -%G_PRIORITY_DEFAULT. - -This will affect the priority of #GSources created with -g_task_attach_source() and the scheduling of tasks run in threads, -and can also be explicitly retrieved later via -g_task_get_priority(). - - - - - - - the #GTask - - - - the [priority][io-priority] of the request - - - - - - Sets or clears @task's return-on-cancel flag. This is only -meaningful for tasks run via g_task_run_in_thread() or -g_task_run_in_thread_sync(). - -If @return_on_cancel is %TRUE, then cancelling @task's -#GCancellable will immediately cause it to return, as though the -task's #GTaskThreadFunc had called -g_task_return_error_if_cancelled() and then returned. - -This allows you to create a cancellable wrapper around an -uninterruptable function. The #GTaskThreadFunc just needs to be -careful that it does not modify any externally-visible state after -it has been cancelled. To do that, the thread should call -g_task_set_return_on_cancel() again to (atomically) set -return-on-cancel %FALSE before making externally-visible changes; -if the task gets cancelled before the return-on-cancel flag could -be changed, g_task_set_return_on_cancel() will indicate this by -returning %FALSE. - -You can disable and re-enable this flag multiple times if you wish. -If the task's #GCancellable is cancelled while return-on-cancel is -%FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE -again will cause the task to be cancelled at that point. - -If the task's #GCancellable is already cancelled before you call -g_task_run_in_thread()/g_task_run_in_thread_sync(), then the -#GTaskThreadFunc will still be run (for consistency), but the task -will also be completed right away. - - - %TRUE if @task's return-on-cancel flag was changed to - match @return_on_cancel. %FALSE if @task has already been - cancelled. - - - - - the #GTask - - - - whether the task returns automatically when - it is cancelled. - - - - - - Sets @task's source tag. You can use this to tag a task return -value with a particular pointer (usually a pointer to the function -doing the tagging) and then later check it using -g_task_get_source_tag() (or g_async_result_is_tagged()) in the -task's "finish" function, to figure out if the response came from a -particular place. - - - - - - - the #GTask - - - - an opaque pointer indicating the source of this task - - - - - - Sets @task's task data (freeing the existing task data, if any). - - - - - - - the #GTask - - - - task-specific data - - - - #GDestroyNotify for @task_data - - - - - - Whether the task has completed, meaning its callback (if set) has been -invoked. This can only happen after g_task_return_pointer(), -g_task_return_error() or one of the other return functions have been called -on the task. - -This property is guaranteed to change from %FALSE to %TRUE exactly once. - -The #GObject::notify signal for this change is emitted in the same main -context as the task’s callback, immediately after that callback is invoked. - - - - - - - - The prototype for a task function to be run in a thread via -g_task_run_in_thread() or g_task_run_in_thread_sync(). - -If the return-on-cancel flag is set on @task, and @cancellable gets -cancelled, then the #GTask will be completed immediately (as though -g_task_return_error_if_cancelled() had been called), without -waiting for the task function to complete. However, the task -function will continue running in its thread in the background. The -function therefore needs to be careful about how it uses -externally-visible state in this case. See -g_task_set_return_on_cancel() for more details. - -Other than in that case, @task will be completed when the -#GTaskThreadFunc returns, not when it calls a -`g_task_return_` function. - - - - - - - the #GTask - - - - @task's source object - - - - @task's task data - - - - @task's #GCancellable, or %NULL - - - - - - This is the subclass of #GSocketConnection that is created -for TCP/IP sockets. - - - Checks if graceful disconnects are used. See -g_tcp_connection_set_graceful_disconnect(). - - - %TRUE if graceful disconnect is used on close, %FALSE otherwise - - - - - a #GTcpConnection - - - - - - This enables graceful disconnects on close. A graceful disconnect -means that we signal the receiving end that the connection is terminated -and wait for it to close the connection before closing the connection. - -A graceful disconnect means that we can be sure that we successfully sent -all the outstanding data to the other end, or get an error reported. -However, it also means we have to wait for all the data to reach the -other side and for it to acknowledge this by closing the socket, which may -take a while. For this reason it is disabled by default. - - - - - - - a #GTcpConnection - - - - Whether to do graceful disconnects or not - - - - - - - - - - - - - - - - - - - - - - - - - A #GTcpWrapperConnection can be used to wrap a #GIOStream that is -based on a #GSocket, but which is not actually a -#GSocketConnection. This is used by #GSocketClient so that it can -always return a #GSocketConnection, even when the connection it has -actually created is not directly a #GSocketConnection. - - - Wraps @base_io_stream and @socket together as a #GSocketConnection. - - - the new #GSocketConnection. - - - - - the #GIOStream to wrap - - - - the #GSocket associated with @base_io_stream - - - - - - Get's @conn's base #GIOStream - - - @conn's base #GIOStream - - - - - a #GTcpWrapperConnection - - - - - - - - - - - - - - - - - - - - - - - - - A helper class for testing code which uses D-Bus without touching the user's -session bus. - -Note that #GTestDBus modifies the user’s environment, calling setenv(). -This is not thread-safe, so all #GTestDBus calls should be completed before -threads are spawned, or should have appropriate locking to ensure no access -conflicts to environment variables shared between #GTestDBus and other -threads. - -## Creating unit tests using GTestDBus - -Testing of D-Bus services can be tricky because normally we only ever run -D-Bus services over an existing instance of the D-Bus daemon thus we -usually don't activate D-Bus services that are not yet installed into the -target system. The #GTestDBus object makes this easier for us by taking care -of the lower level tasks such as running a private D-Bus daemon and looking -up uninstalled services in customizable locations, typically in your source -code tree. - -The first thing you will need is a separate service description file for the -D-Bus daemon. Typically a `services` subdirectory of your `tests` directory -is a good place to put this file. - -The service file should list your service along with an absolute path to the -uninstalled service executable in your source tree. Using autotools we would -achieve this by adding a file such as `my-server.service.in` in the services -directory and have it processed by configure. -|[ - [D-BUS Service] - Name=org.gtk.GDBus.Examples.ObjectManager - Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server -]| -You will also need to indicate this service directory in your test -fixtures, so you will need to pass the path while compiling your -test cases. Typically this is done with autotools with an added -preprocessor flag specified to compile your tests such as: -|[ - -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" -]| - Once you have a service definition file which is local to your source tree, -you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. - -An example of a test fixture for D-Bus services can be found -here: -[gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c) - -Note that these examples only deal with isolating the D-Bus aspect of your -service. To successfully run isolated unit tests on your service you may need -some additional modifications to your test case fixture. For example; if your -service uses GSettings and installs a schema then it is important that your test service -not load the schema in the ordinary installed location (chances are that your service -and schema files are not yet installed, or worse; there is an older version of the -schema file sitting in the install location). - -Most of the time we can work around these obstacles using the -environment. Since the environment is inherited by the D-Bus daemon -created by #GTestDBus and then in turn inherited by any services the -D-Bus daemon activates, using the setup routine for your fixture is -a practical place to help sandbox your runtime environment. For the -rather typical GSettings case we can work around this by setting -`GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas -in the above fixture_setup() routine. - -The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved -by compiling the schemas locally as a step before running test cases, an autotools setup might -do the following in the directory holding schemas: -|[ - all-am: - $(GLIB_COMPILE_SCHEMAS) . - - CLEANFILES += gschemas.compiled -]| - - Create a new #GTestDBus object. - - - a new #GTestDBus. - - - - - a #GTestDBusFlags - - - - - - Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test -won't use user's session bus. - -This is useful for unit tests that want to verify behaviour when no session -bus is running. It is not necessary to call this if unit test already calls -g_test_dbus_up() before acquiring the session bus. - - - - - - - Add a path where dbus-daemon will look up .service files. This can't be -called after g_test_dbus_up(). - - - - - - - a #GTestDBus - - - - path to a directory containing .service files - - - - - - Stop the session bus started by g_test_dbus_up(). - -This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() -to be destroyed. This is done to ensure that the next unit test won't get a -leaked singleton from this test. - - - - - - - a #GTestDBus - - - - - - Get the address on which dbus-daemon is running. If g_test_dbus_up() has not -been called yet, %NULL is returned. This can be used with -g_dbus_connection_new_for_address(). - - - the address of the bus, or %NULL. - - - - - a #GTestDBus - - - - - - Get the flags of the #GTestDBus object. - - - the value of #GTestDBus:flags property - - - - - a #GTestDBus - - - - - - Stop the session bus started by g_test_dbus_up(). - -Unlike g_test_dbus_down(), this won't verify the #GDBusConnection -singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit -tests wanting to verify behaviour after the session bus has been stopped -can use this function but should still call g_test_dbus_down() when done. - - - - - - - a #GTestDBus - - - - - - Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this -call, it is safe for unit tests to start sending messages on the session bus. - -If this function is called from setup callback of g_test_add(), -g_test_dbus_down() must be called in its teardown callback. - -If this function is called from unit test's main(), then g_test_dbus_down() -must be called after g_test_run(). - - - - - - - a #GTestDBus - - - - - - #GTestDBusFlags specifying the behaviour of the D-Bus session. - - - - - Flags to define future #GTestDBus behaviour. - - No flags. - - - - #GThemedIcon is an implementation of #GIcon that supports icon themes. -#GThemedIcon contains a list of all of the icons present in an icon -theme, so that icons can be looked up quickly. #GThemedIcon does -not provide actual pixmaps for icons, just the icon names. -Ideally something like gtk_icon_theme_choose_icon() should be used to -resolve the list of names so that fallback icons work nicely with -themes that inherit other themes. - - - - Creates a new themed icon for @iconname. - - - a new #GThemedIcon. - - - - - a string containing an icon name. - - - - - - Creates a new themed icon for @iconnames. - - - a new #GThemedIcon - - - - - an array of strings containing icon names. - - - - - - the length of the @iconnames array, or -1 if @iconnames is - %NULL-terminated - - - - - - Creates a new themed icon for @iconname, and all the names -that can be created by shortening @iconname at '-' characters. - -In the following example, @icon1 and @icon2 are equivalent: -|[<!-- language="C" --> -const char *names[] = { - "gnome-dev-cdrom-audio", - "gnome-dev-cdrom", - "gnome-dev", - "gnome" -}; - -icon1 = g_themed_icon_new_from_names (names, 4); -icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); -]| - - - a new #GThemedIcon. - - - - - a string containing an icon name - - - - - - Append a name to the list of icons from within @icon. - -Note that doing so invalidates the hash computed by prior calls -to g_icon_hash(). - - - - - - - a #GThemedIcon - - - - name of icon to append to list of icons from within @icon. - - - - - - Gets the names of icons from within @icon. - - - a list of icon names. - - - - - - - a #GThemedIcon. - - - - - - Prepend a name to the list of icons from within @icon. - -Note that doing so invalidates the hash computed by prior calls -to g_icon_hash(). - - - - - - - a #GThemedIcon - - - - name of icon to prepend to list of icons from within @icon. - - - - - - The icon name. - - - - A %NULL-terminated array of icon names. - - - - - - Whether to use the default fallbacks found by shortening the icon name -at '-' characters. If the "names" array has more than one element, -ignores any past the first. - -For example, if the icon name was "gnome-dev-cdrom-audio", the array -would become -|[<!-- language="C" --> -{ - "gnome-dev-cdrom-audio", - "gnome-dev-cdrom", - "gnome-dev", - "gnome", - NULL -}; -]| - - - - - - - - A #GThreadedSocketService is a simple subclass of #GSocketService -that handles incoming connections by creating a worker thread and -dispatching the connection to it by emitting the -#GThreadedSocketService::run signal in the new thread. - -The signal handler may perform blocking IO and need not return -until the connection is closed. - -The service is implemented using a thread pool, so there is a -limited amount of threads available to serve incoming requests. -The service automatically stops the #GSocketService from accepting -new connections when all threads are busy. - -As with #GSocketService, you may connect to #GThreadedSocketService::run, -or subclass and override the default handler. - - - Creates a new #GThreadedSocketService with no listeners. Listeners -must be added with one of the #GSocketListener "add" methods. - - - a new #GSocketService. - - - - - the maximal number of threads to execute concurrently - handling incoming clients, -1 means no limit - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The ::run signal is emitted in a worker thread in response to an -incoming connection. This thread is dedicated to handling -@connection and may perform blocking IO. The signal handler need -not return until the connection is closed. - - %TRUE to stop further signal handlers from being called - - - - - a new #GSocketConnection object. - - - - the source_object passed to g_socket_listener_add_address(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The client authentication mode for a #GTlsServerConnection. - - client authentication not required - - - client authentication is requested - - - client authentication is required - - - - TLS (Transport Layer Security, aka SSL) and DTLS backend. - - - Gets the default #GTlsBackend for the system. - - - a #GTlsBackend - - - - - Gets the default #GTlsDatabase used to verify TLS connections. - - - the default database, which should be - unreffed when done. - - - - - the #GTlsBackend - - - - - - Checks if DTLS is supported. DTLS support may not be available even if TLS -support is available, and vice-versa. - - - whether DTLS is supported - - - - - the #GTlsBackend - - - - - - Checks if TLS is supported; if this returns %FALSE for the default -#GTlsBackend, it means no "real" TLS backend is available. - - - whether or not TLS is supported - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend's #GTlsCertificate implementation. - - - the #GType of @backend's #GTlsCertificate - implementation. - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend's #GTlsClientConnection implementation. - - - the #GType of @backend's #GTlsClientConnection - implementation. - - - - - the #GTlsBackend - - - - - - Gets the default #GTlsDatabase used to verify TLS connections. - - - the default database, which should be - unreffed when done. - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend’s #GDtlsClientConnection implementation. - - - the #GType of @backend’s #GDtlsClientConnection - implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend’s #GDtlsServerConnection implementation. - - - the #GType of @backend’s #GDtlsServerConnection - implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend's #GTlsFileDatabase implementation. - - - the #GType of backend's #GTlsFileDatabase implementation. - - - - - the #GTlsBackend - - - - - - Gets the #GType of @backend's #GTlsServerConnection implementation. - - - the #GType of @backend's #GTlsServerConnection - implementation. - - - - - the #GTlsBackend - - - - - - Set the default #GTlsDatabase used to verify TLS connections - -Any subsequent call to g_tls_backend_get_default_database() will return -the database set in this call. Existing databases and connections are not -modified. - -Setting a %NULL default database will reset to using the system default -database as if g_tls_backend_set_default_database() had never been called. - - - - - - - the #GTlsBackend - - - - the #GTlsDatabase - - - - - - Checks if DTLS is supported. DTLS support may not be available even if TLS -support is available, and vice-versa. - - - whether DTLS is supported - - - - - the #GTlsBackend - - - - - - Checks if TLS is supported; if this returns %FALSE for the default -#GTlsBackend, it means no "real" TLS backend is available. - - - whether or not TLS is supported - - - - - the #GTlsBackend - - - - - - - Provides an interface for describing TLS-related types. - - - The parent interface. - - - - - - - whether or not TLS is supported - - - - - the #GTlsBackend - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the default database, which should be - unreffed when done. - - - - - the #GTlsBackend - - - - - - - - - - whether DTLS is supported - - - - - the #GTlsBackend - - - - - - - - - - - - - - - - - - - - - - - - A certificate used for TLS authentication and encryption. -This can represent either a certificate only (eg, the certificate -received by a client from a server), or the combination of -a certificate and a private key (which is needed when acting as a -#GTlsServerConnection). - - - Creates a #GTlsCertificate from the PEM-encoded data in @file. The -returned certificate will be the first certificate found in @file. As -of GLib 2.44, if @file contains more certificates it will try to load -a certificate chain. All certificates will be verified in the order -found (top-level certificate should be the last one in the file) and -the #GTlsCertificate:issuer property of each certificate will be set -accordingly if the verification succeeds. If any certificate in the -chain cannot be verified, the first certificate in the file will -still be returned. - -If @file cannot be read or parsed, the function will return %NULL and -set @error. Otherwise, this behaves like -g_tls_certificate_new_from_pem(). - - - the new certificate, or %NULL on error - - - - - file containing a PEM-encoded certificate to import - - - - - - Creates a #GTlsCertificate from the PEM-encoded data in @cert_file -and @key_file. The returned certificate will be the first certificate -found in @cert_file. As of GLib 2.44, if @cert_file contains more -certificates it will try to load a certificate chain. All -certificates will be verified in the order found (top-level -certificate should be the last one in the file) and the -#GTlsCertificate:issuer property of each certificate will be set -accordingly if the verification succeeds. If any certificate in the -chain cannot be verified, the first certificate in the file will -still be returned. - -If either file cannot be read or parsed, the function will return -%NULL and set @error. Otherwise, this behaves like -g_tls_certificate_new_from_pem(). - - - the new certificate, or %NULL on error - - - - - file containing one or more PEM-encoded - certificates to import - - - - file containing a PEM-encoded private key - to import - - - - - - Creates a #GTlsCertificate from the PEM-encoded data in @data. If -@data includes both a certificate and a private key, then the -returned certificate will include the private key data as well. (See -the #GTlsCertificate:private-key-pem property for information about -supported formats.) - -The returned certificate will be the first certificate found in -@data. As of GLib 2.44, if @data contains more certificates it will -try to load a certificate chain. All certificates will be verified in -the order found (top-level certificate should be the last one in the -file) and the #GTlsCertificate:issuer property of each certificate -will be set accordingly if the verification succeeds. If any -certificate in the chain cannot be verified, the first certificate in -the file will still be returned. - - - the new certificate, or %NULL if @data is invalid - - - - - PEM-encoded certificate data - - - - the length of @data, or -1 if it's 0-terminated. - - - - - - Creates one or more #GTlsCertificates from the PEM-encoded -data in @file. If @file cannot be read or parsed, the function will -return %NULL and set @error. If @file does not contain any -PEM-encoded certificates, this will return an empty list and not -set @error. - - - a -#GList containing #GTlsCertificate objects. You must free the list -and its contents when you are done with it. - - - - - - - file containing PEM-encoded certificates to import - - - - - - This verifies @cert and returns a set of #GTlsCertificateFlags -indicating any problems found with it. This can be used to verify a -certificate outside the context of making a connection, or to -check a certificate against a CA that is not part of the system -CA database. - -If @identity is not %NULL, @cert's name(s) will be compared against -it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return -value if it does not match. If @identity is %NULL, that bit will -never be set in the return value. - -If @trusted_ca is not %NULL, then @cert (or one of the certificates -in its chain) must be signed by it, or else -%G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If -@trusted_ca is %NULL, that bit will never be set in the return -value. - -(All other #GTlsCertificateFlags values will always be set or unset -as appropriate.) - - - the appropriate #GTlsCertificateFlags - - - - - a #GTlsCertificate - - - - the expected peer identity - - - - the certificate of a trusted authority - - - - - - Gets the #GTlsCertificate representing @cert's issuer, if known - - - The certificate of @cert's issuer, -or %NULL if @cert is self-signed or signed with an unknown -certificate. - - - - - a #GTlsCertificate - - - - - - Check if two #GTlsCertificate objects represent the same certificate. -The raw DER byte data of the two certificates are checked for equality. -This has the effect that two certificates may compare equal even if -their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or -#GTlsCertificate:private-key-pem properties differ. - - - whether the same or not - - - - - first certificate to compare - - - - second certificate to compare - - - - - - This verifies @cert and returns a set of #GTlsCertificateFlags -indicating any problems found with it. This can be used to verify a -certificate outside the context of making a connection, or to -check a certificate against a CA that is not part of the system -CA database. - -If @identity is not %NULL, @cert's name(s) will be compared against -it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return -value if it does not match. If @identity is %NULL, that bit will -never be set in the return value. - -If @trusted_ca is not %NULL, then @cert (or one of the certificates -in its chain) must be signed by it, or else -%G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If -@trusted_ca is %NULL, that bit will never be set in the return -value. - -(All other #GTlsCertificateFlags values will always be set or unset -as appropriate.) - - - the appropriate #GTlsCertificateFlags - - - - - a #GTlsCertificate - - - - the expected peer identity - - - - the certificate of a trusted authority - - - - - - The DER (binary) encoded representation of the certificate. -This property and the #GTlsCertificate:certificate-pem property -represent the same data, just in different forms. - - - - - - The PEM (ASCII) encoded representation of the certificate. -This property and the #GTlsCertificate:certificate -property represent the same data, just in different forms. - - - - A #GTlsCertificate representing the entity that issued this -certificate. If %NULL, this means that the certificate is either -self-signed, or else the certificate of the issuer is not -available. - - - - The DER (binary) encoded representation of the certificate's -private key, in either PKCS#1 format or unencrypted PKCS#8 -format. This property (or the #GTlsCertificate:private-key-pem -property) can be set when constructing a key (eg, from a file), -but cannot be read. - -PKCS#8 format is supported since 2.32; earlier releases only -support PKCS#1. You can use the `openssl rsa` -tool to convert PKCS#8 keys to PKCS#1. - - - - - - The PEM (ASCII) encoded representation of the certificate's -private key in either PKCS#1 format ("`BEGIN RSA PRIVATE -KEY`") or unencrypted PKCS#8 format ("`BEGIN -PRIVATE KEY`"). This property (or the -#GTlsCertificate:private-key property) can be set when -constructing a key (eg, from a file), but cannot be read. - -PKCS#8 format is supported since 2.32; earlier releases only -support PKCS#1. You can use the `openssl rsa` -tool to convert PKCS#8 keys to PKCS#1. - - - - - - - - - - - - - - - - - - - the appropriate #GTlsCertificateFlags - - - - - a #GTlsCertificate - - - - the expected peer identity - - - - the certificate of a trusted authority - - - - - - - - - - - - - A set of flags describing TLS certification validation. This can be -used to set which validation steps to perform (eg, with -g_tls_client_connection_set_validation_flags()), or to describe why -a particular certificate was rejected (eg, in -#GTlsConnection::accept-certificate). - - The signing certificate authority is - not known. - - - The certificate does not match the - expected identity of the site that it was retrieved from. - - - The certificate's activation time - is still in the future - - - The certificate has expired - - - The certificate has been revoked - according to the #GTlsConnection's certificate revocation list. - - - The certificate's algorithm is - considered insecure. - - - Some other error occurred validating - the certificate - - - the combination of all of the above - flags - - - - - - - Flags for g_tls_interaction_request_certificate(), -g_tls_interaction_request_certificate_async(), and -g_tls_interaction_invoke_request_certificate(). - - No flags - - - - #GTlsClientConnection is the client-side subclass of -#GTlsConnection, representing a client-side TLS connection. - - - - Creates a new #GTlsClientConnection wrapping @base_io_stream (which -must have pollable input and output streams) which is assumed to -communicate with the server identified by @server_identity. - -See the documentation for #GTlsConnection:base-io-stream for restrictions -on when application code can run operations on the @base_io_stream after -this function has returned. - - - the new -#GTlsClientConnection, or %NULL on error - - - - - the #GIOStream to wrap - - - - the expected identity of the server - - - - - - Possibly copies session state from one connection to another, for use -in TLS session resumption. This is not normally needed, but may be -used when the same session needs to be used between different -endpoints, as is required by some protocols, such as FTP over TLS. -@source should have already completed a handshake and, since TLS 1.3, -it should have been used to read data at least once. @conn should not -have completed a handshake. - -It is not possible to know whether a call to this function will -actually do anything. Because session resumption is normally used -only for performance benefit, the TLS backend might not implement -this function. Even if implemented, it may not actually succeed in -allowing @conn to resume @source's TLS session, because the server -may not have sent a session resumption token to @source, or it may -refuse to accept the token from @conn. There is no way to know -whether a call to this function is actually successful. - -Using this function is not required to benefit from session -resumption. If the TLS backend supports session resumption, the -session will be resumed automatically if it is possible to do so -without weakening the privacy guarantees normally provided by TLS, -without need to call this function. For example, with TLS 1.3, -a session ticket will be automatically copied from any -#GTlsClientConnection that has previously received session tickets -from the server, provided a ticket is available that has not -previously been used for session resumption, since session ticket -reuse would be a privacy weakness. Using this function causes the -ticket to be copied without regard for privacy considerations. - - - - - - - a #GTlsClientConnection - - - - a #GTlsClientConnection - - - - - - Possibly copies session state from one connection to another, for use -in TLS session resumption. This is not normally needed, but may be -used when the same session needs to be used between different -endpoints, as is required by some protocols, such as FTP over TLS. -@source should have already completed a handshake and, since TLS 1.3, -it should have been used to read data at least once. @conn should not -have completed a handshake. - -It is not possible to know whether a call to this function will -actually do anything. Because session resumption is normally used -only for performance benefit, the TLS backend might not implement -this function. Even if implemented, it may not actually succeed in -allowing @conn to resume @source's TLS session, because the server -may not have sent a session resumption token to @source, or it may -refuse to accept the token from @conn. There is no way to know -whether a call to this function is actually successful. - -Using this function is not required to benefit from session -resumption. If the TLS backend supports session resumption, the -session will be resumed automatically if it is possible to do so -without weakening the privacy guarantees normally provided by TLS, -without need to call this function. For example, with TLS 1.3, -a session ticket will be automatically copied from any -#GTlsClientConnection that has previously received session tickets -from the server, provided a ticket is available that has not -previously been used for session resumption, since session ticket -reuse would be a privacy weakness. Using this function causes the -ticket to be copied without regard for privacy considerations. - - - - - - - a #GTlsClientConnection - - - - a #GTlsClientConnection - - - - - - Gets the list of distinguished names of the Certificate Authorities -that the server will accept certificates from. This will be set -during the TLS handshake if the server requests a certificate. -Otherwise, it will be %NULL. - -Each item in the list is a #GByteArray which contains the complete -subject DN of the certificate authority. - - - the list of -CA DNs. You should unref each element with g_byte_array_unref() and then -the free the list with g_list_free(). - - - - - - - - - the #GTlsClientConnection - - - - - - Gets @conn's expected server identity - - - a #GSocketConnectable describing the -expected server identity, or %NULL if the expected identity is not -known. - - - - - the #GTlsClientConnection - - - - - - SSL 3.0 is no longer supported. See -g_tls_client_connection_set_use_ssl3() for details. - SSL 3.0 is insecure. - - - %FALSE - - - - - the #GTlsClientConnection - - - - - - Gets @conn's validation flags - - - the validation flags - - - - - the #GTlsClientConnection - - - - - - Sets @conn's expected server identity, which is used both to tell -servers on virtual hosts which certificate to present, and also -to let @conn know what name to look for in the certificate when -performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - - - - - - - the #GTlsClientConnection - - - - a #GSocketConnectable describing the expected server identity - - - - - - Since GLib 2.42.1, SSL 3.0 is no longer supported. - -From GLib 2.42.1 through GLib 2.62, this function could be used to -force use of TLS 1.0, the lowest-supported TLS protocol version at -the time. In the past, this was needed to connect to broken TLS -servers that exhibited protocol version intolerance. Such servers -are no longer common, and using TLS 1.0 is no longer considered -acceptable. - -Since GLib 2.64, this function does nothing. - SSL 3.0 is insecure. - - - - - - - the #GTlsClientConnection - - - - a #gboolean, ignored - - - - - - Sets @conn's validation flags, to override the default set of -checks performed when validating a server certificate. By default, -%G_TLS_CERTIFICATE_VALIDATE_ALL is used. - - - - - - - the #GTlsClientConnection - - - - the #GTlsCertificateFlags to use - - - - - - A list of the distinguished names of the Certificate Authorities -that the server will accept client certificates signed by. If the -server requests a client certificate during the handshake, then -this property will be set after the handshake completes. - -Each item in the list is a #GByteArray which contains the complete -subject DN of the certificate authority. - - - - - - A #GSocketConnectable describing the identity of the server that -is expected on the other end of the connection. - -If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in -#GTlsClientConnection:validation-flags, this object will be used -to determine the expected identify of the remote end of the -connection; if #GTlsClientConnection:server-identity is not set, -or does not match the identity presented by the server, then the -%G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. - -In addition to its use in verifying the server certificate, -this is also used to give a hint to the server about what -certificate we expect, which is useful for servers that serve -virtual hosts. - - - - SSL 3.0 is no longer supported. See -g_tls_client_connection_set_use_ssl3() for details. - SSL 3.0 is insecure. - - - - What steps to perform when validating a certificate received from -a server. Server certificates that fail to validate in all of the -ways indicated here will be rejected unless the application -overrides the default via #GTlsConnection::accept-certificate. - - - - - vtable for a #GTlsClientConnection implementation. - - - The parent interface. - - - - - - - - - - - a #GTlsClientConnection - - - - a #GTlsClientConnection - - - - - - - - #GTlsConnection is the base TLS connection class type, which wraps -a #GIOStream and provides TLS encryption on top of it. Its -subclasses, #GTlsClientConnection and #GTlsServerConnection, -implement client-side and server-side TLS, respectively. - -For DTLS (Datagram TLS) support, see #GDtlsConnection. - - - - - - - - - - - - - - - - - - - - Attempts a TLS handshake on @conn. - -On the client side, it is never necessary to call this method; -although the connection needs to perform a handshake after -connecting (or after sending a "STARTTLS"-type command), -#GTlsConnection will handle this for you automatically when you try -to send or receive data on the connection. You can call -g_tls_connection_handshake() manually if you want to know whether -the initial handshake succeeded or failed (as opposed to just -immediately trying to use @conn to read or write, in which case, -if it fails, it may not be possible to tell if it failed before or -after completing the handshake), but beware that servers may reject -client authentication after the handshake has completed, so a -successful handshake does not indicate the connection will be usable. - -Likewise, on the server side, although a handshake is necessary at -the beginning of the communication, you do not need to call this -function explicitly unless you want clearer error reporting. - -Previously, calling g_tls_connection_handshake() after the initial -handshake would trigger a rehandshake; however, this usage was -deprecated in GLib 2.60 because rehandshaking was removed from the -TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after -the initial handshake will no longer do anything. - -When using a #GTlsConnection created by #GSocketClient, the -#GSocketClient performs the initial handshake, so calling this -function manually is not recommended. - -#GTlsConnection::accept_certificate may be emitted during the -handshake. - - - success or failure - - - - - a #GTlsConnection - - - - a #GCancellable, or %NULL - - - - - - Asynchronously performs a TLS handshake on @conn. See -g_tls_connection_handshake() for more information. - - - - - - - a #GTlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS handshake operation. See -g_tls_connection_handshake() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GTlsConnection - - - - a #GAsyncResult. - - - - - - Used by #GTlsConnection implementations to emit the -#GTlsConnection::accept-certificate signal. - - - %TRUE if one of the signal handlers has returned - %TRUE to accept @peer_cert - - - - - a #GTlsConnection - - - - the peer's #GTlsCertificate - - - - the problems with @peer_cert - - - - - - Gets @conn's certificate, as set by -g_tls_connection_set_certificate(). - - - @conn's certificate, or %NULL - - - - - a #GTlsConnection - - - - - - Gets the certificate database that @conn uses to verify -peer certificates. See g_tls_connection_set_database(). - - - the certificate database that @conn uses or %NULL - - - - - a #GTlsConnection - - - - - - Get the object that will be used to interact with the user. It will be used -for things like prompting the user for passwords. If %NULL is returned, then -no user interaction will occur for this connection. - - - The interaction object. - - - - - a connection - - - - - - Gets the name of the application-layer protocol negotiated during -the handshake. - -If the peer did not use the ALPN extension, or did not advertise a -protocol that matched one of @conn's protocols, or the TLS backend -does not support ALPN, then this will be %NULL. See -g_tls_connection_set_advertised_protocols(). - - - the negotiated protocol, or %NULL - - - - - a #GTlsConnection - - - - - - Gets @conn's peer's certificate after the handshake has completed. -(It is not set during the emission of -#GTlsConnection::accept-certificate.) - - - @conn's peer's certificate, or %NULL - - - - - a #GTlsConnection - - - - - - Gets the errors associated with validating @conn's peer's -certificate, after the handshake has completed. (It is not set -during the emission of #GTlsConnection::accept-certificate.) - - - @conn's peer's certificate errors - - - - - a #GTlsConnection - - - - - - Gets @conn rehandshaking mode. See -g_tls_connection_set_rehandshake_mode() for details. - Changing the rehandshake mode is no longer - required for compatibility. Also, rehandshaking has been removed - from the TLS protocol in TLS 1.3. - - - %G_TLS_REHANDSHAKE_SAFELY - - - - - a #GTlsConnection - - - - - - Tests whether or not @conn expects a proper TLS close notification -when the connection is closed. See -g_tls_connection_set_require_close_notify() for details. - - - %TRUE if @conn requires a proper TLS close -notification. - - - - - a #GTlsConnection - - - - - - Gets whether @conn uses the system certificate database to verify -peer certificates. See g_tls_connection_set_use_system_certdb(). - Use g_tls_connection_get_database() instead - - - whether @conn uses the system certificate database - - - - - a #GTlsConnection - - - - - - Attempts a TLS handshake on @conn. - -On the client side, it is never necessary to call this method; -although the connection needs to perform a handshake after -connecting (or after sending a "STARTTLS"-type command), -#GTlsConnection will handle this for you automatically when you try -to send or receive data on the connection. You can call -g_tls_connection_handshake() manually if you want to know whether -the initial handshake succeeded or failed (as opposed to just -immediately trying to use @conn to read or write, in which case, -if it fails, it may not be possible to tell if it failed before or -after completing the handshake), but beware that servers may reject -client authentication after the handshake has completed, so a -successful handshake does not indicate the connection will be usable. - -Likewise, on the server side, although a handshake is necessary at -the beginning of the communication, you do not need to call this -function explicitly unless you want clearer error reporting. - -Previously, calling g_tls_connection_handshake() after the initial -handshake would trigger a rehandshake; however, this usage was -deprecated in GLib 2.60 because rehandshaking was removed from the -TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after -the initial handshake will no longer do anything. - -When using a #GTlsConnection created by #GSocketClient, the -#GSocketClient performs the initial handshake, so calling this -function manually is not recommended. - -#GTlsConnection::accept_certificate may be emitted during the -handshake. - - - success or failure - - - - - a #GTlsConnection - - - - a #GCancellable, or %NULL - - - - - - Asynchronously performs a TLS handshake on @conn. See -g_tls_connection_handshake() for more information. - - - - - - - a #GTlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - Finish an asynchronous TLS handshake operation. See -g_tls_connection_handshake() for more information. - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GTlsConnection - - - - a #GAsyncResult. - - - - - - Sets the list of application-layer protocols to advertise that the -caller is willing to speak on this connection. The -Application-Layer Protocol Negotiation (ALPN) extension will be -used to negotiate a compatible protocol with the peer; use -g_tls_connection_get_negotiated_protocol() to find the negotiated -protocol after the handshake. Specifying %NULL for the the value -of @protocols will disable ALPN negotiation. - -See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) -for a list of registered protocol IDs. - - - - - - - a #GTlsConnection - - - - a %NULL-terminated - array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - - - - - - - - This sets the certificate that @conn will present to its peer -during the TLS handshake. For a #GTlsServerConnection, it is -mandatory to set this, and that will normally be done at construct -time. - -For a #GTlsClientConnection, this is optional. If a handshake fails -with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server -requires a certificate, and if you try connecting again, you should -call this method first. You can call -g_tls_client_connection_get_accepted_cas() on the failed connection -to get a list of Certificate Authorities that the server will -accept certificates from. - -(It is also possible that a server will allow the connection with -or without a certificate; in that case, if you don't provide a -certificate, you can tell that the server requested one by the fact -that g_tls_client_connection_get_accepted_cas() will return -non-%NULL.) - - - - - - - a #GTlsConnection - - - - the certificate to use for @conn - - - - - - Sets the certificate database that is used to verify peer certificates. -This is set to the default database by default. See -g_tls_backend_get_default_database(). If set to %NULL, then -peer certificate validation will always set the -%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning -#GTlsConnection::accept-certificate will always be emitted on -client-side connections, unless that bit is not set in -#GTlsClientConnection:validation-flags). - - - - - - - a #GTlsConnection - - - - a #GTlsDatabase - - - - - - Set the object that will be used to interact with the user. It will be used -for things like prompting the user for passwords. - -The @interaction argument will normally be a derived subclass of -#GTlsInteraction. %NULL can also be provided if no user interaction -should occur for this connection. - - - - - - - a connection - - - - an interaction object, or %NULL - - - - - - Since GLib 2.64, changing the rehandshake mode is no longer supported -and will have no effect. With TLS 1.3, rehandshaking has been removed from -the TLS protocol, replaced by separate post-handshake authentication and -rekey operations. - Changing the rehandshake mode is no longer - required for compatibility. Also, rehandshaking has been removed - from the TLS protocol in TLS 1.3. - - - - - - - a #GTlsConnection - - - - the rehandshaking mode - - - - - - Sets whether or not @conn expects a proper TLS close notification -before the connection is closed. If this is %TRUE (the default), -then @conn will expect to receive a TLS close notification from its -peer before the connection is closed, and will return a -%G_TLS_ERROR_EOF error if the connection is closed without proper -notification (since this may indicate a network error, or -man-in-the-middle attack). - -In some protocols, the application will know whether or not the -connection was closed cleanly based on application-level data -(because the application-level data includes a length field, or is -somehow self-delimiting); in this case, the close notify is -redundant and sometimes omitted. (TLS 1.1 explicitly allows this; -in TLS 1.0 it is technically an error, but often done anyway.) You -can use g_tls_connection_set_require_close_notify() to tell @conn -to allow an "unannounced" connection close, in which case the close -will show up as a 0-length read, as in a non-TLS -#GSocketConnection, and it is up to the application to check that -the data has been fully received. - -Note that this only affects the behavior when the peer closes the -connection; when the application calls g_io_stream_close() itself -on @conn, this will send a close notification regardless of the -setting of this property. If you explicitly want to do an unclean -close, you can close @conn's #GTlsConnection:base-io-stream rather -than closing @conn itself, but note that this may only be done when no other -operations are pending on @conn or the base I/O stream. - - - - - - - a #GTlsConnection - - - - whether or not to require close notification - - - - - - Sets whether @conn uses the system certificate database to verify -peer certificates. This is %TRUE by default. If set to %FALSE, then -peer certificate validation will always set the -%G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning -#GTlsConnection::accept-certificate will always be emitted on -client-side connections, unless that bit is not set in -#GTlsClientConnection:validation-flags). - Use g_tls_connection_set_database() instead - - - - - - - a #GTlsConnection - - - - whether to use the system certificate database - - - - - - The list of application-layer protocols that the connection -advertises that it is willing to speak. See -g_tls_connection_set_advertised_protocols(). - - - - - - The #GIOStream that the connection wraps. The connection holds a reference -to this stream, and may run operations on the stream from other threads -throughout its lifetime. Consequently, after the #GIOStream has been -constructed, application code may only run its own operations on this -stream when no #GIOStream operations are running. - - - - The connection's certificate; see -g_tls_connection_set_certificate(). - - - - The certificate database to use when verifying this TLS connection. -If no certificate database is set, then the default database will be -used. See g_tls_backend_get_default_database(). - - - - A #GTlsInteraction object to be used when the connection or certificate -database need to interact with the user. This will be used to prompt the -user for passwords where necessary. - - - - The application-layer protocol negotiated during the TLS -handshake. See g_tls_connection_get_negotiated_protocol(). - - - - The connection's peer's certificate, after the TLS handshake has -completed and the certificate has been accepted. Note in -particular that this is not yet set during the emission of -#GTlsConnection::accept-certificate. - -(You can watch for a #GObject::notify signal on this property to -detect when a handshake has occurred.) - - - - The errors noticed-and-ignored while verifying -#GTlsConnection:peer-certificate. Normally this should be 0, but -it may not be if #GTlsClientConnection:validation-flags is not -%G_TLS_CERTIFICATE_VALIDATE_ALL, or if -#GTlsConnection::accept-certificate overrode the default -behavior. - - - - The rehandshaking mode. See -g_tls_connection_set_rehandshake_mode(). - The rehandshake mode is ignored. - - - - Whether or not proper TLS close notification is required. -See g_tls_connection_set_require_close_notify(). - - - - Whether or not the system certificate database will be used to -verify peer certificates. See -g_tls_connection_set_use_system_certdb(). - Use GTlsConnection:database instead - - - - - - - - - - Emitted during the TLS handshake after the peer certificate has -been received. You can examine @peer_cert's certification path by -calling g_tls_certificate_get_issuer() on it. - -For a client-side connection, @peer_cert is the server's -certificate, and the signal will only be emitted if the -certificate was not acceptable according to @conn's -#GTlsClientConnection:validation_flags. If you would like the -certificate to be accepted despite @errors, return %TRUE from the -signal handler. Otherwise, if no handler accepts the certificate, -the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. - -For a server-side connection, @peer_cert is the certificate -presented by the client, if this was requested via the server's -#GTlsServerConnection:authentication_mode. On the server side, -the signal is always emitted when the client presents a -certificate, and the certificate will only be accepted if a -handler returns %TRUE. - -Note that if this signal is emitted as part of asynchronous I/O -in the main thread, then you should not attempt to interact with -the user before returning from the signal handler. If you want to -let the user decide whether or not to accept the certificate, you -would have to return %FALSE from the signal handler on the first -attempt, and then after the connection attempt returns a -%G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and -if the user decides to accept the certificate, remember that fact, -create a new connection, and return %TRUE from the signal handler -the next time. - -If you are doing I/O in another thread, you do not -need to worry about this, and can simply block in the signal -handler until the UI thread returns an answer. - - %TRUE to accept @peer_cert (which will also -immediately end the signal emission). %FALSE to allow the signal -emission to continue, which will cause the handshake to fail if -no one else overrides it. - - - - - the peer's #GTlsCertificate - - - - the problems with @peer_cert. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - success or failure - - - - - a #GTlsConnection - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GTlsConnection - - - - the [I/O priority][io-priority] of the request - - - - a #GCancellable, or %NULL - - - - callback to call when the handshake is complete - - - - the data to pass to the callback function - - - - - - - - - - %TRUE on success, %FALSE on failure, in which -case @error will be set. - - - - - a #GTlsConnection - - - - a #GAsyncResult. - - - - - - - - - - - - - - - - #GTlsDatabase is used to look up certificates and other information -from a certificate or key store. It is an abstract base class which -TLS library specific subtypes override. - -A #GTlsDatabase may be accessed from multiple threads by the TLS backend. -All implementations are required to be fully thread-safe. - -Most common client applications will not directly interact with -#GTlsDatabase. It is used internally by #GTlsConnection. - - - Create a handle string for the certificate. The database will only be able -to create a handle for certificates that originate from the database. In -cases where the database cannot create a handle for a certificate, %NULL -will be returned. - -This handle should be stable across various instances of the application, -and between applications. If a certificate is modified in the database, -then it is not guaranteed that this handle will continue to point to it. - - - a newly allocated string containing the -handle. - - - - - a #GTlsDatabase - - - - certificate for which to create a handle. - - - - - - Look up a certificate by its handle. - -The handle should have been created by calling -g_tls_database_create_certificate_handle() on a #GTlsDatabase object of -the same TLS backend. The handle is designed to remain valid across -instantiations of the database. - -If the handle is no longer valid, or does not point to a certificate in -this database, then %NULL will be returned. - -This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform -the lookup operation asynchronously. - - - a newly allocated -#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up a certificate by its handle in the database. See -g_tls_database_lookup_certificate_for_handle() for more information. - - - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup of a certificate by its handle. See -g_tls_database_lookup_certificate_for_handle() for more information. - -If the handle is no longer valid, or does not point to a certificate in -this database, then %NULL will be returned. - - - a newly allocated #GTlsCertificate object. -Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Look up the issuer of @certificate in the database. - -The #GTlsCertificate:issuer property -of @certificate is not modified, and the two certificates are not hooked -into a chain. - -This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform -the lookup operation asynchronously. - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up the issuer of @certificate in the database. See -g_tls_database_lookup_certificate_issuer() for more information. - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup issuer operation. See -g_tls_database_lookup_certificate_issuer() for more information. - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Look up certificates issued by this issuer in the database. - -This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform -the lookup operation asynchronously. - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up certificates issued by this issuer in the database. See -g_tls_database_lookup_certificates_issued_by() for more information. - -The database may choose to hold a reference to the issuer byte array for the duration -of of this asynchronous operation. The byte array should not be modified during -this time. - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup of certificates. See -g_tls_database_lookup_certificates_issued_by() for more information. - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Determines the validity of a certificate chain after looking up and -adding any missing certificates to the chain. - -@chain is a chain of #GTlsCertificate objects each pointing to the next -certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially -consist of one or more certificates. After the verification process is -complete, @chain may be modified by adding missing certificates, or removing -extra certificates. If a certificate anchor was found, then it is added to -the @chain. - -@purpose describes the purpose (or usage) for which the certificate -is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER -which means that the certificate is being used to authenticate a server -(and we are acting as the client). - -The @identity is used to check for pinned certificates (trust exceptions) -in the database. These will override the normal verification process on a -host by host basis. - -Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be -used. - -If @chain is found to be valid, then the return value will be 0. If -@chain is found to be invalid, then the return value will indicate -the problems found. If the function is unable to determine whether -@chain is valid or not (eg, because @cancellable is triggered -before it completes) then the return value will be -%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set -accordingly. @error is not set when @chain is successfully analyzed -but found to be invalid. - -This function can block, use g_tls_database_verify_chain_async() to perform -the verification operation asynchronously. - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - - - Asynchronously determines the validity of a certificate chain after -looking up and adding any missing certificates to the chain. See -g_tls_database_verify_chain() for more information. - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous verify chain operation. See -g_tls_database_verify_chain() for more information. - -If @chain is found to be valid, then the return value will be 0. If -@chain is found to be invalid, then the return value will indicate -the problems found. If the function is unable to determine whether -@chain is valid or not (eg, because @cancellable is triggered -before it completes) then the return value will be -%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set -accordingly. @error is not set when @chain is successfully analyzed -but found to be invalid. - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Create a handle string for the certificate. The database will only be able -to create a handle for certificates that originate from the database. In -cases where the database cannot create a handle for a certificate, %NULL -will be returned. - -This handle should be stable across various instances of the application, -and between applications. If a certificate is modified in the database, -then it is not guaranteed that this handle will continue to point to it. - - - a newly allocated string containing the -handle. - - - - - a #GTlsDatabase - - - - certificate for which to create a handle. - - - - - - Look up a certificate by its handle. - -The handle should have been created by calling -g_tls_database_create_certificate_handle() on a #GTlsDatabase object of -the same TLS backend. The handle is designed to remain valid across -instantiations of the database. - -If the handle is no longer valid, or does not point to a certificate in -this database, then %NULL will be returned. - -This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform -the lookup operation asynchronously. - - - a newly allocated -#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up a certificate by its handle in the database. See -g_tls_database_lookup_certificate_for_handle() for more information. - - - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup of a certificate by its handle. See -g_tls_database_lookup_certificate_for_handle() for more information. - -If the handle is no longer valid, or does not point to a certificate in -this database, then %NULL will be returned. - - - a newly allocated #GTlsCertificate object. -Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Look up the issuer of @certificate in the database. - -The #GTlsCertificate:issuer property -of @certificate is not modified, and the two certificates are not hooked -into a chain. - -This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform -the lookup operation asynchronously. - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up the issuer of @certificate in the database. See -g_tls_database_lookup_certificate_issuer() for more information. - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup issuer operation. See -g_tls_database_lookup_certificate_issuer() for more information. - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Look up certificates issued by this issuer in the database. - -This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform -the lookup operation asynchronously. - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - - - Asynchronously look up certificates issued by this issuer in the database. See -g_tls_database_lookup_certificates_issued_by() for more information. - -The database may choose to hold a reference to the issuer byte array for the duration -of of this asynchronous operation. The byte array should not be modified during -this time. - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous lookup of certificates. See -g_tls_database_lookup_certificates_issued_by() for more information. - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - Determines the validity of a certificate chain after looking up and -adding any missing certificates to the chain. - -@chain is a chain of #GTlsCertificate objects each pointing to the next -certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially -consist of one or more certificates. After the verification process is -complete, @chain may be modified by adding missing certificates, or removing -extra certificates. If a certificate anchor was found, then it is added to -the @chain. - -@purpose describes the purpose (or usage) for which the certificate -is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER -which means that the certificate is being used to authenticate a server -(and we are acting as the client). - -The @identity is used to check for pinned certificates (trust exceptions) -in the database. These will override the normal verification process on a -host by host basis. - -Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be -used. - -If @chain is found to be valid, then the return value will be 0. If -@chain is found to be invalid, then the return value will indicate -the problems found. If the function is unable to determine whether -@chain is valid or not (eg, because @cancellable is triggered -before it completes) then the return value will be -%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set -accordingly. @error is not set when @chain is successfully analyzed -but found to be invalid. - -This function can block, use g_tls_database_verify_chain_async() to perform -the verification operation asynchronously. - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - - - Asynchronously determines the validity of a certificate chain after -looking up and adding any missing certificates to the chain. See -g_tls_database_verify_chain() for more information. - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - Finish an asynchronous verify chain operation. See -g_tls_database_verify_chain() for more information. - -If @chain is found to be valid, then the return value will be 0. If -@chain is found to be invalid, then the return value will indicate -the problems found. If the function is unable to determine whether -@chain is valid or not (eg, because @cancellable is triggered -before it completes) then the return value will be -%G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set -accordingly. @error is not set when @chain is successfully analyzed -but found to be invalid. - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - - - - - - - - The class for #GTlsDatabase. Derived classes should implement the various -virtual methods. _async and _finish methods have a default -implementation that runs the corresponding sync method in a thread. - - - - - - - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate chain - - - - the purpose that this certificate chain will be used for. - - - - the expected peer identity - - - - used to interact with the user if necessary - - - - additional verify flags - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - - - - - the appropriate #GTlsCertificateFlags which represents the -result of verification. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - - - - - a newly allocated string containing the -handle. - - - - - a #GTlsDatabase - - - - certificate for which to create a handle. - - - - - - - - - - a newly allocated -#GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GTlsDatabase - - - - a certificate handle - - - - used to interact with the user if necessary - - - - Flags which affect the lookup. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - - - - - a newly allocated #GTlsCertificate object. -Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - - - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GTlsDatabase - - - - a #GTlsCertificate - - - - used to interact with the user if necessary - - - - flags which affect the lookup operation - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - - - - - a newly allocated issuer #GTlsCertificate, -or %NULL. Use g_object_unref() to release the certificate. - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - - - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - - - - - - - - - - - a #GTlsDatabase - - - - a #GByteArray which holds the DER encoded issuer DN. - - - - - - used to interact with the user if necessary - - - - Flags which affect the lookup operation. - - - - a #GCancellable, or %NULL - - - - callback to call when the operation completes - - - - the data to pass to the callback function - - - - - - - - - - a newly allocated list of #GTlsCertificate -objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. - - - - - - - a #GTlsDatabase - - - - a #GAsyncResult. - - - - - - - - - - - - - Flags for g_tls_database_lookup_certificate_for_handle(), -g_tls_database_lookup_certificate_issuer(), -and g_tls_database_lookup_certificates_issued_by(). - - No lookup flags - - - Restrict lookup to certificates that have - a private key. - - - - - - - Flags for g_tls_database_verify_chain(). - - No verification flags - - - - An error code used with %G_TLS_ERROR in a #GError returned from a -TLS-related routine. - - No TLS provider is available - - - Miscellaneous TLS error - - - The certificate presented could not - be parsed or failed validation. - - - The TLS handshake failed because the - peer does not seem to be a TLS server. - - - The TLS handshake failed because the - peer's certificate was not acceptable. - - - The TLS handshake failed because - the server requested a client-side certificate, but none was - provided. See g_tls_connection_set_certificate(). - - - The TLS connection was closed without proper - notice, which may indicate an attack. See - g_tls_connection_set_require_close_notify(). - - - The TLS handshake failed - because the client sent the fallback SCSV, indicating a protocol - downgrade attack. Since: 2.60 - - - Gets the TLS error quark. - - a #GQuark. - - - - - - #GTlsFileDatabase is implemented by #GTlsDatabase objects which load -their certificate information from a file. It is an interface which -TLS library specific subtypes implement. - - - - Creates a new #GTlsFileDatabase which uses anchor certificate authorities -in @anchors to verify certificate chains. - -The certificates in @anchors must be PEM encoded. - - - the new -#GTlsFileDatabase, or %NULL on error - - - - - filename of anchor certificate authorities. - - - - - - The path to a file containing PEM encoded certificate authority -root anchors. The certificates in this file will be treated as -root authorities for the purpose of verifying other certificates -via the g_tls_database_verify_chain() operation. - - - - - Provides an interface for #GTlsFileDatabase implementations. - - - The parent interface. - - - - - - - - - - #GTlsInteraction provides a mechanism for the TLS connection and database -code to interact with the user. It can be used to ask the user for passwords. - -To use a #GTlsInteraction with a TLS connection use -g_tls_connection_set_interaction(). - -Callers should instantiate a derived class that implements the various -interaction methods to show the required dialogs. - -Callers should use the 'invoke' functions like -g_tls_interaction_invoke_ask_password() to run interaction methods. These -functions make sure that the interaction is invoked in the main loop -and not in the current thread, if the current thread is not running the -main loop. - -Derived classes can choose to implement whichever interactions methods they'd -like to support by overriding those virtual methods in their class -initialization function. Any interactions not implemented will return -%G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, -it must also implement the corresponding finish method. - - - Run synchronous interaction to ask the user for a password. In general, -g_tls_interaction_invoke_ask_password() should be used instead of this -function. - -Derived subclasses usually implement a password prompt, although they may -also choose to provide a password from elsewhere. The @password value will -be filled in and then @callback will be called. Alternatively the user may -abort this password request, which will usually abort the TLS connection. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - - - Run asynchronous interaction to ask the user for a password. In general, -g_tls_interaction_invoke_ask_password() should be used instead of this -function. - -Derived subclasses usually implement a password prompt, although they may -also choose to provide a password from elsewhere. The @password value will -be filled in and then @callback will be called. Alternatively the user may -abort this password request, which will usually abort the TLS connection. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - -Certain implementations may not support immediate cancellation. - - - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - Complete an ask password user interaction request. This should be once -the g_tls_interaction_ask_password_async() completion callback is called. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed -to g_tls_interaction_ask_password() will have its password filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - Run synchronous interaction to ask the user to choose a certificate to use -with the connection. In general, g_tls_interaction_invoke_request_certificate() -should be used instead of this function. - -Derived subclasses usually implement a certificate selector, although they may -also choose to provide a certificate from elsewhere. Alternatively the user may -abort this certificate request, which will usually abort the TLS connection. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection -passed to g_tls_interaction_request_certificate() will have had its -#GTlsConnection:certificate filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - - - Run asynchronous interaction to ask the user for a certificate to use with -the connection. In general, g_tls_interaction_invoke_request_certificate() should -be used instead of this function. - -Derived subclasses usually implement a certificate selector, although they may -also choose to provide a certificate from elsewhere. @callback will be called -when the operation completes. Alternatively the user may abort this certificate -request, which will usually abort the TLS connection. - - - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - Complete a request certificate user interaction request. This should be once -the g_tls_interaction_request_certificate_async() completion callback is called. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection -passed to g_tls_interaction_request_certificate_async() will have had its -#GTlsConnection:certificate filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - Run synchronous interaction to ask the user for a password. In general, -g_tls_interaction_invoke_ask_password() should be used instead of this -function. - -Derived subclasses usually implement a password prompt, although they may -also choose to provide a password from elsewhere. The @password value will -be filled in and then @callback will be called. Alternatively the user may -abort this password request, which will usually abort the TLS connection. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - - - Run asynchronous interaction to ask the user for a password. In general, -g_tls_interaction_invoke_ask_password() should be used instead of this -function. - -Derived subclasses usually implement a password prompt, although they may -also choose to provide a password from elsewhere. The @password value will -be filled in and then @callback will be called. Alternatively the user may -abort this password request, which will usually abort the TLS connection. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - -Certain implementations may not support immediate cancellation. - - - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - Complete an ask password user interaction request. This should be once -the g_tls_interaction_ask_password_async() completion callback is called. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed -to g_tls_interaction_ask_password() will have its password filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - Invoke the interaction to ask the user for a password. It invokes this -interaction in the main loop, specifically the #GMainContext returned by -g_main_context_get_thread_default() when the interaction is created. This -is called by called by #GTlsConnection or #GTlsDatabase to ask the user -for a password. - -Derived subclasses usually implement a password prompt, although they may -also choose to provide a password from elsewhere. The @password value will -be filled in and then @callback will be called. Alternatively the user may -abort this password request, which will usually abort the TLS connection. - -The implementation can either be a synchronous (eg: modal dialog) or an -asynchronous one (eg: modeless dialog). This function will take care of -calling which ever one correctly. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - - - Invoke the interaction to ask the user to choose a certificate to -use with the connection. It invokes this interaction in the main -loop, specifically the #GMainContext returned by -g_main_context_get_thread_default() when the interaction is -created. This is called by called by #GTlsConnection when the peer -requests a certificate during the handshake. - -Derived subclasses usually implement a certificate selector, -although they may also choose to provide a certificate from -elsewhere. Alternatively the user may abort this certificate -request, which may or may not abort the TLS connection. - -The implementation can either be a synchronous (eg: modal dialog) or an -asynchronous one (eg: modeless dialog). This function will take care of -calling which ever one correctly. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the certificate request interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - - - Run synchronous interaction to ask the user to choose a certificate to use -with the connection. In general, g_tls_interaction_invoke_request_certificate() -should be used instead of this function. - -Derived subclasses usually implement a certificate selector, although they may -also choose to provide a certificate from elsewhere. Alternatively the user may -abort this certificate request, which will usually abort the TLS connection. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection -passed to g_tls_interaction_request_certificate() will have had its -#GTlsConnection:certificate filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may -not support immediate cancellation. - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - - - Run asynchronous interaction to ask the user for a certificate to use with -the connection. In general, g_tls_interaction_invoke_request_certificate() should -be used instead of this function. - -Derived subclasses usually implement a certificate selector, although they may -also choose to provide a certificate from elsewhere. @callback will be called -when the operation completes. Alternatively the user may abort this certificate -request, which will usually abort the TLS connection. - - - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - Complete a request certificate user interaction request. This should be once -the g_tls_interaction_request_certificate_async() completion callback is called. - -If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection -passed to g_tls_interaction_request_certificate_async() will have had its -#GTlsConnection:certificate filled in. - -If the interaction is cancelled by the cancellation object, or by the -user then %G_TLS_INTERACTION_FAILED will be returned with an error that -contains a %G_IO_ERROR_CANCELLED error code. - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - - - - - - - - The class for #GTlsInteraction. Derived classes implement the various -virtual interaction methods to handle TLS interactions. - -Derived classes can choose to implement whichever interactions methods they'd -like to support by overriding those virtual methods in their class -initialization function. If a derived class implements an async method, -it must also implement the corresponding finish method. - -The synchronous interaction methods should implement to display modal dialogs, -and the asynchronous methods to display modeless dialogs. - -If the user cancels an interaction, then the result should be -%G_TLS_INTERACTION_FAILED and the error should be set with a domain of -%G_IO_ERROR and code of %G_IO_ERROR_CANCELLED. - - - - - - - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - - - - - - - - - - - a #GTlsInteraction object - - - - a #GTlsPassword object - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - - - - - The status of the ask password interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - - - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - - - - - - - - - - - a #GTlsInteraction object - - - - a #GTlsConnection object - - - - flags providing more information about the request - - - - an optional #GCancellable cancellation object - - - - will be called when the interaction completes - - - - data to pass to the @callback - - - - - - - - - - The status of the request certificate interaction. - - - - - a #GTlsInteraction object - - - - the result passed to the callback - - - - - - - - - - - - - - - - #GTlsInteractionResult is returned by various functions in #GTlsInteraction -when finishing an interaction request. - - The interaction was unhandled (i.e. not - implemented). - - - The interaction completed, and resulting data - is available. - - - The interaction has failed, or was cancelled. - and the operation should be aborted. - - - - Holds a password used in TLS. - - - Create a new #GTlsPassword object. - - - The newly allocated password object - - - - - the password flags - - - - description of what the password is for - - - - - - - - - - - - - - - - - Get the password value. If @length is not %NULL then it will be -filled in with the length of the password value. (Note that the -password value is not nul-terminated, so you can only pass %NULL -for @length in contexts where you know the password will have a -certain fixed length.) - - - The password value (owned by the password object). - - - - - a #GTlsPassword object - - - - location to place the length of the password. - - - - - - Provide the value for this password. - -The @value will be owned by the password object, and later freed using -the @destroy function callback. - -Specify the @length, for a non-nul-terminated password. Pass -1 as -@length if using a nul-terminated password, and @length will be -calculated automatically. (Note that the terminating nul is not -considered part of the password in this case.) - - - - - - - a #GTlsPassword object - - - - the value for the password - - - - - - the length of the password, or -1 - - - - a function to use to free the password. - - - - - - Get a description string about what the password will be used for. - - - The description of the password. - - - - - a #GTlsPassword object - - - - - - Get flags about the password. - - - The flags about the password. - - - - - a #GTlsPassword object - - - - - - Get the password value. If @length is not %NULL then it will be -filled in with the length of the password value. (Note that the -password value is not nul-terminated, so you can only pass %NULL -for @length in contexts where you know the password will have a -certain fixed length.) - - - The password value (owned by the password object). - - - - - a #GTlsPassword object - - - - location to place the length of the password. - - - - - - Get a user readable translated warning. Usually this warning is a -representation of the password flags returned from -g_tls_password_get_flags(). - - - The warning. - - - - - a #GTlsPassword object - - - - - - Set a description string about what the password will be used for. - - - - - - - a #GTlsPassword object - - - - The description of the password - - - - - - Set flags about the password. - - - - - - - a #GTlsPassword object - - - - The flags about the password - - - - - - Set the value for this password. The @value will be copied by the password -object. - -Specify the @length, for a non-nul-terminated password. Pass -1 as -@length if using a nul-terminated password, and @length will be -calculated automatically. (Note that the terminating nul is not -considered part of the password in this case.) - - - - - - - a #GTlsPassword object - - - - the new password value - - - - - - the length of the password, or -1 - - - - - - Provide the value for this password. - -The @value will be owned by the password object, and later freed using -the @destroy function callback. - -Specify the @length, for a non-nul-terminated password. Pass -1 as -@length if using a nul-terminated password, and @length will be -calculated automatically. (Note that the terminating nul is not -considered part of the password in this case.) - - - - - - - a #GTlsPassword object - - - - the value for the password - - - - - - the length of the password, or -1 - - - - a function to use to free the password. - - - - - - Set a user readable translated warning. Usually this warning is a -representation of the password flags returned from -g_tls_password_get_flags(). - - - - - - - a #GTlsPassword object - - - - The user readable warning - - - - - - - - - - - - - - - - - - - - - - Class structure for #GTlsPassword. - - - - - - - - - The password value (owned by the password object). - - - - - a #GTlsPassword object - - - - location to place the length of the password. - - - - - - - - - - - - - - a #GTlsPassword object - - - - the value for the password - - - - - - the length of the password, or -1 - - - - a function to use to free the password. - - - - - - - - - - - - - - - - - - - - - - - - - - Various flags for the password. - - No flags - - - The password was wrong, and the user should retry. - - - Hint to the user that the password has been - wrong many times, and the user may not have many chances left. - - - Hint to the user that this is the last try to get - this password right. - - - - - - - When to allow rehandshaking. See -g_tls_connection_set_rehandshake_mode(). - Changing the rehandshake mode is no longer - required for compatibility. Also, rehandshaking has been removed - from the TLS protocol in TLS 1.3. - - Never allow rehandshaking - - - Allow safe rehandshaking only - - - Allow unsafe rehandshaking - - - - #GTlsServerConnection is the server-side subclass of #GTlsConnection, -representing a server-side TLS connection. - - - - Creates a new #GTlsServerConnection wrapping @base_io_stream (which -must have pollable input and output streams). - -See the documentation for #GTlsConnection:base-io-stream for restrictions -on when application code can run operations on the @base_io_stream after -this function has returned. - - - the new -#GTlsServerConnection, or %NULL on error - - - - - the #GIOStream to wrap - - - - the default server certificate, or %NULL - - - - - - The #GTlsAuthenticationMode for the server. This can be changed -before calling g_tls_connection_handshake() if you want to -rehandshake with a different mode from the initial handshake. - - - - - vtable for a #GTlsServerConnection implementation. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This is the subclass of #GSocketConnection that is created -for UNIX domain sockets. - -It contains functions to do some of the UNIX socket specific -functionality like passing file descriptors. - -Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific -GIO interfaces, thus you have to use the `gio-unix-2.0.pc` -pkg-config file when using it. - - - Receives credentials from the sending end of the connection. The -sending end has to call g_unix_connection_send_credentials() (or -similar) for this to work. - -As well as reading the credentials this also reads (and discards) a -single byte from the stream, as this is required for credentials -passing to work on some implementations. - -This method can be expected to be available on the following platforms: - -- Linux since GLib 2.26 -- FreeBSD since GLib 2.26 -- GNU/kFreeBSD since GLib 2.36 -- Solaris, Illumos and OpenSolaris since GLib 2.40 -- GNU/Hurd since GLib 2.40 - -Other ways to exchange credentials with a foreign peer includes the -#GUnixCredentialsMessage type and g_socket_get_credentials() function. - - - Received credentials on success (free with -g_object_unref()), %NULL if @error is set. - - - - - A #GUnixConnection. - - - - A #GCancellable or %NULL. - - - - - - Asynchronously receive credentials. - -For more details, see g_unix_connection_receive_credentials() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. You can then call -g_unix_connection_receive_credentials_finish() to get the result of the operation. - - - - - - - A #GUnixConnection. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous receive credentials operation started with -g_unix_connection_receive_credentials_async(). - - - a #GCredentials, or %NULL on error. - Free the returned object with g_object_unref(). - - - - - A #GUnixConnection. - - - - a #GAsyncResult. - - - - - - Receives a file descriptor from the sending end of the connection. -The sending end has to call g_unix_connection_send_fd() for this -to work. - -As well as reading the fd this also reads a single byte from the -stream, as this is required for fd passing to work on some -implementations. - - - a file descriptor on success, -1 on error. - - - - - a #GUnixConnection - - - - optional #GCancellable object, %NULL to ignore - - - - - - Passes the credentials of the current user the receiving side -of the connection. The receiving end has to call -g_unix_connection_receive_credentials() (or similar) to accept the -credentials. - -As well as sending the credentials this also writes a single NUL -byte to the stream, as this is required for credentials passing to -work on some implementations. - -This method can be expected to be available on the following platforms: - -- Linux since GLib 2.26 -- FreeBSD since GLib 2.26 -- GNU/kFreeBSD since GLib 2.36 -- Solaris, Illumos and OpenSolaris since GLib 2.40 -- GNU/Hurd since GLib 2.40 - -Other ways to exchange credentials with a foreign peer includes the -#GUnixCredentialsMessage type and g_socket_get_credentials() function. - - - %TRUE on success, %FALSE if @error is set. - - - - - A #GUnixConnection. - - - - A #GCancellable or %NULL. - - - - - - Asynchronously send credentials. - -For more details, see g_unix_connection_send_credentials() which is -the synchronous version of this call. - -When the operation is finished, @callback will be called. You can then call -g_unix_connection_send_credentials_finish() to get the result of the operation. - - - - - - - A #GUnixConnection. - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to callback function - - - - - - Finishes an asynchronous send credentials operation started with -g_unix_connection_send_credentials_async(). - - - %TRUE if the operation was successful, otherwise %FALSE. - - - - - A #GUnixConnection. - - - - a #GAsyncResult. - - - - - - Passes a file descriptor to the receiving side of the -connection. The receiving end has to call g_unix_connection_receive_fd() -to accept the file descriptor. - -As well as sending the fd this also writes a single byte to the -stream, as this is required for fd passing to work on some -implementations. - - - a %TRUE on success, %NULL on error. - - - - - a #GUnixConnection - - - - a file descriptor - - - - optional #GCancellable object, %NULL to ignore. - - - - - - - - - - - - - - - - - - - - - - This #GSocketControlMessage contains a #GCredentials instance. It -may be sent using g_socket_send_message() and received using -g_socket_receive_message() over UNIX sockets (ie: sockets in the -%G_SOCKET_FAMILY_UNIX family). - -For an easier way to send and receive credentials over -stream-oriented UNIX sockets, see -g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials(). To receive credentials of -a foreign process connected to a socket, use -g_socket_get_credentials(). - - - Creates a new #GUnixCredentialsMessage with credentials matching the current processes. - - - a new #GUnixCredentialsMessage - - - - - Creates a new #GUnixCredentialsMessage holding @credentials. - - - a new #GUnixCredentialsMessage - - - - - A #GCredentials object. - - - - - - Checks if passing #GCredentials on a #GSocket is supported on this platform. - - - %TRUE if supported, %FALSE otherwise - - - - - Gets the credentials stored in @message. - - - A #GCredentials instance. Do not free, it is owned by @message. - - - - - A #GUnixCredentialsMessage. - - - - - - The credentials stored in the message. - - - - - - - - - - - Class structure for #GUnixCredentialsMessage. - - - - - - - - - - - - - - - - - - - - - - - - - - A #GUnixFDList contains a list of file descriptors. It owns the file -descriptors that it contains, closing them when finalized. - -It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in -the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() -and received using g_socket_receive_message(). - -Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - Creates a new #GUnixFDList containing no file descriptors. - - - a new #GUnixFDList - - - - - Creates a new #GUnixFDList containing the file descriptors given in -@fds. The file descriptors become the property of the new list and -may no longer be used by the caller. The array itself is owned by -the caller. - -Each file descriptor in the array should be set to close-on-exec. - -If @n_fds is -1 then @fds must be terminated with -1. - - - a new #GUnixFDList - - - - - the initial list of file descriptors - - - - - - the length of #fds, or -1 - - - - - - Adds a file descriptor to @list. - -The file descriptor is duplicated using dup(). You keep your copy -of the descriptor and the copy contained in @list will be closed -when @list is finalized. - -A possible cause of failure is exceeding the per-process or -system-wide file descriptor limit. - -The index of the file descriptor in the list is returned. If you use -this index with g_unix_fd_list_get() then you will receive back a -duplicated copy of the same file descriptor. - - - the index of the appended fd in case of success, else -1 - (and @error is set) - - - - - a #GUnixFDList - - - - a valid open file descriptor - - - - - - Gets a file descriptor out of @list. - -@index_ specifies the index of the file descriptor to get. It is a -programmer error for @index_ to be out of range; see -g_unix_fd_list_get_length(). - -The file descriptor is duplicated using dup() and set as -close-on-exec before being returned. You must call close() on it -when you are done. - -A possible cause of failure is exceeding the per-process or -system-wide file descriptor limit. - - - the file descriptor, or -1 in case of error - - - - - a #GUnixFDList - - - - the index into the list - - - - - - Gets the length of @list (ie: the number of file descriptors -contained within). - - - the length of @list - - - - - a #GUnixFDList - - - - - - Returns the array of file descriptors that is contained in this -object. - -After this call, the descriptors remain the property of @list. The -caller must not close them and must not free the array. The array is -valid only until @list is changed in any way. - -If @length is non-%NULL then it is set to the number of file -descriptors in the returned array. The returned array is also -terminated with -1. - -This function never returns %NULL. In case there are no file -descriptors contained in @list, an empty array is returned. - - - an array of file - descriptors - - - - - - - a #GUnixFDList - - - - pointer to the length of the returned - array, or %NULL - - - - - - Returns the array of file descriptors that is contained in this -object. - -After this call, the descriptors are no longer contained in -@list. Further calls will return an empty list (unless more -descriptors have been added). - -The return result of this function must be freed with g_free(). -The caller is also responsible for closing all of the file -descriptors. The file descriptors in the array are set to -close-on-exec. - -If @length is non-%NULL then it is set to the number of file -descriptors in the returned array. The returned array is also -terminated with -1. - -This function never returns %NULL. In case there are no file -descriptors contained in @list, an empty array is returned. - - - an array of file - descriptors - - - - - - - a #GUnixFDList - - - - pointer to the length of the returned - array, or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This #GSocketControlMessage contains a #GUnixFDList. -It may be sent using g_socket_send_message() and received using -g_socket_receive_message() over UNIX sockets (ie: sockets in the -%G_SOCKET_FAMILY_UNIX family). The file descriptors are copied -between processes by the kernel. - -For an easier way to send and receive file descriptors over -stream-oriented UNIX sockets, see g_unix_connection_send_fd() and -g_unix_connection_receive_fd(). - -Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - Creates a new #GUnixFDMessage containing an empty file descriptor -list. - - - a new #GUnixFDMessage - - - - - Creates a new #GUnixFDMessage containing @list. - - - a new #GUnixFDMessage - - - - - a #GUnixFDList - - - - - - Adds a file descriptor to @message. - -The file descriptor is duplicated using dup(). You keep your copy -of the descriptor and the copy contained in @message will be closed -when @message is finalized. - -A possible cause of failure is exceeding the per-process or -system-wide file descriptor limit. - - - %TRUE in case of success, else %FALSE (and @error is set) - - - - - a #GUnixFDMessage - - - - a valid open file descriptor - - - - - - Gets the #GUnixFDList contained in @message. This function does not -return a reference to the caller, but the returned list is valid for -the lifetime of @message. - - - the #GUnixFDList from @message - - - - - a #GUnixFDMessage - - - - - - Returns the array of file descriptors that is contained in this -object. - -After this call, the descriptors are no longer contained in -@message. Further calls will return an empty list (unless more -descriptors have been added). - -The return result of this function must be freed with g_free(). -The caller is also responsible for closing all of the file -descriptors. - -If @length is non-%NULL then it is set to the number of file -descriptors in the returned array. The returned array is also -terminated with -1. - -This function never returns %NULL. In case there are no file -descriptors contained in @message, an empty array is returned. - - - an array of file - descriptors - - - - - - - a #GUnixFDMessage - - - - pointer to the length of the returned - array, or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GUnixInputStream implements #GInputStream for reading from a UNIX -file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do -asynchronous I/O. If it refers to a regular file, it will fall back -to doing asynchronous I/O in another thread.) - -Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - - - Creates a new #GUnixInputStream for the given @fd. - -If @close_fd is %TRUE, the file descriptor will be closed -when the stream is closed. - - - a new #GUnixInputStream - - - - - a UNIX file descriptor - - - - %TRUE to close the file descriptor when done - - - - - - Returns whether the file descriptor of @stream will be -closed when the stream is closed. - - - %TRUE if the file descriptor is closed when done - - - - - a #GUnixInputStream - - - - - - Return the UNIX file descriptor that the stream reads from. - - - The file descriptor of @stream - - - - - a #GUnixInputStream - - - - - - Sets whether the file descriptor of @stream shall be closed -when the stream is closed. - - - - - - - a #GUnixInputStream - - - - %TRUE to close the file descriptor when done - - - - - - Whether to close the file descriptor when the stream is closed. - - - - The file descriptor that the stream reads from. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). -This corresponds roughly to a mtab entry. - - - - Watches #GUnixMounts for changes. - - - Deprecated alias for g_unix_mount_monitor_get(). - -This function was never a true constructor, which is why it was -renamed. - Use g_unix_mount_monitor_get() instead. - - - a #GUnixMountMonitor. - - - - - Gets the #GUnixMountMonitor for the current thread-default main -context. - -The mount monitor can be used to monitor for changes to the list of -mounted filesystems as well as the list of mount points (ie: fstab -entries). - -You must only call g_object_unref() on the return value from under -the same main context as you called this function. - - - the #GUnixMountMonitor. - - - - - This function does nothing. - -Before 2.44, this was a partially-effective way of controlling the -rate at which events would be reported under some uncommon -circumstances. Since @mount_monitor is a singleton, it also meant -that calling this function would have side effects for other users of -the monitor. - This function does nothing. Don't call it. - - - - - - - a #GUnixMountMonitor - - - - a integer with the limit in milliseconds to - poll for changes. - - - - - - Emitted when the unix mount points have changed. - - - - - - Emitted when the unix mounts have changed. - - - - - - - - - - Defines a Unix mount point (e.g. <filename>/dev</filename>). -This corresponds roughly to a fstab entry. - - - Compares two unix mount points. - - - 1, 0 or -1 if @mount1 is greater than, equal to, -or less than @mount2, respectively. - - - - - a #GUnixMount. - - - - a #GUnixMount. - - - - - - Makes a copy of @mount_point. - - - a new #GUnixMountPoint - - - - - a #GUnixMountPoint. - - - - - - Frees a unix mount point. - - - - - - - unix mount point to free. - - - - - - Gets the device path for a unix mount point. - - - a string containing the device path. - - - - - a #GUnixMountPoint. - - - - - - Gets the file system type for the mount point. - - - a string containing the file system type. - - - - - a #GUnixMountPoint. - - - - - - Gets the mount path for a unix mount point. - - - a string containing the mount path. - - - - - a #GUnixMountPoint. - - - - - - Gets the options for the mount point. - - - a string containing the options. - - - - - a #GUnixMountPoint. - - - - - - Guesses whether a Unix mount point can be ejected. - - - %TRUE if @mount_point is deemed to be ejectable. - - - - - a #GUnixMountPoint - - - - - - Guesses the icon of a Unix mount point. - - - a #GIcon - - - - - a #GUnixMountPoint - - - - - - Guesses the name of a Unix mount point. -The result is a translated string. - - - A newly allocated string that must - be freed with g_free() - - - - - a #GUnixMountPoint - - - - - - Guesses the symbolic icon of a Unix mount point. - - - a #GIcon - - - - - a #GUnixMountPoint - - - - - - Checks if a unix mount point is a loopback device. - - - %TRUE if the mount point is a loopback. %FALSE otherwise. - - - - - a #GUnixMountPoint. - - - - - - Checks if a unix mount point is read only. - - - %TRUE if a mount point is read only. - - - - - a #GUnixMountPoint. - - - - - - Checks if a unix mount point is mountable by the user. - - - %TRUE if the mount point is user mountable. - - - - - a #GUnixMountPoint. - - - - - - - #GUnixOutputStream implements #GOutputStream for writing to a UNIX -file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do -asynchronous I/O. If it refers to a regular file, it will fall back -to doing asynchronous I/O in another thread.) - -Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file -when using it. - - - - - Creates a new #GUnixOutputStream for the given @fd. - -If @close_fd, is %TRUE, the file descriptor will be closed when -the output stream is destroyed. - - - a new #GOutputStream - - - - - a UNIX file descriptor - - - - %TRUE to close the file descriptor when done - - - - - - Returns whether the file descriptor of @stream will be -closed when the stream is closed. - - - %TRUE if the file descriptor is closed when done - - - - - a #GUnixOutputStream - - - - - - Return the UNIX file descriptor that the stream writes to. - - - The file descriptor of @stream - - - - - a #GUnixOutputStream - - - - - - Sets whether the file descriptor of @stream shall be closed -when the stream is closed. - - - - - - - a #GUnixOutputStream - - - - %TRUE to close the file descriptor when done - - - - - - Whether to close the file descriptor when the stream is closed. - - - - The file descriptor that the stream writes to. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Support for UNIX-domain (also known as local) sockets. - -UNIX domain sockets are generally visible in the filesystem. -However, some systems support abstract socket names which are not -visible in the filesystem and not affected by the filesystem -permissions, visibility, etc. Currently this is only supported -under Linux. If you attempt to use abstract sockets on other -systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED -errors. You can use g_unix_socket_address_abstract_names_supported() -to see if abstract names are supported. - -Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file -when using it. - - - - Creates a new #GUnixSocketAddress for @path. - -To create abstract socket addresses, on systems that support that, -use g_unix_socket_address_new_abstract(). - - - a new #GUnixSocketAddress - - - - - the socket path - - - - - - Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED -#GUnixSocketAddress for @path. - Use g_unix_socket_address_new_with_type(). - - - a new #GUnixSocketAddress - - - - - the abstract name - - - - - - the length of @path, or -1 - - - - - - Creates a new #GUnixSocketAddress of type @type with name @path. - -If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to -calling g_unix_socket_address_new(). - -If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be -ignored. - -If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len -bytes of @path will be copied to the socket's path, and only those -bytes will be considered part of the name. (If @path_len is -1, -then @path is assumed to be NUL-terminated.) For example, if @path -was "test", then calling g_socket_address_get_native_size() on the -returned socket would return 7 (2 bytes of overhead, 1 byte for the -abstract-socket indicator byte, and 4 bytes for the name "test"). - -If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then -@path_len bytes of @path will be copied to the socket's path, the -rest of the path will be padded with 0 bytes, and the entire -zero-padded buffer will be considered the name. (As above, if -@path_len is -1, then @path is assumed to be NUL-terminated.) In -this case, g_socket_address_get_native_size() will always return -the full size of a `struct sockaddr_un`, although -g_unix_socket_address_get_path_len() will still return just the -length of @path. - -%G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over -%G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, -when connecting to a server created by another process, you must -use the appropriate type corresponding to how that process created -its listening socket. - - - a new #GUnixSocketAddress - - - - - the name - - - - - - the length of @path, or -1 - - - - a #GUnixSocketAddressType - - - - - - Checks if abstract UNIX domain socket names are supported. - - - %TRUE if supported, %FALSE otherwise - - - - - Gets @address's type. - - - a #GUnixSocketAddressType - - - - - a #GInetSocketAddress - - - - - - Tests if @address is abstract. - Use g_unix_socket_address_get_address_type() - - - %TRUE if the address is abstract, %FALSE otherwise - - - - - a #GInetSocketAddress - - - - - - Gets @address's path, or for abstract sockets the "name". - -Guaranteed to be zero-terminated, but an abstract socket -may contain embedded zeros, and thus you should use -g_unix_socket_address_get_path_len() to get the true length -of this string. - - - the path for @address - - - - - a #GInetSocketAddress - - - - - - Gets the length of @address's path. - -For details, see g_unix_socket_address_get_path(). - - - the length of the path - - - - - a #GInetSocketAddress - - - - - - Whether or not this is an abstract address - Use #GUnixSocketAddress:address-type, which -distinguishes between zero-padded and non-zero-padded -abstract addresses. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of name used by a #GUnixSocketAddress. -%G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain -socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS -indicates a socket not bound to any name (eg, a client-side socket, -or a socket created with socketpair()). - -For abstract sockets, there are two incompatible ways of naming -them; the man pages suggest using the entire `struct sockaddr_un` -as the name, padding the unused parts of the %sun_path field with -zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. -However, many programs instead just use a portion of %sun_path, and -pass an appropriate smaller length to bind() or connect(). This is -%G_UNIX_SOCKET_ADDRESS_ABSTRACT. - - invalid - - - anonymous - - - a filesystem path - - - an abstract name - - - an abstract name, 0-padded - to the full length of a unix socket name - - - - - - - - - - - - - - - - - - Extension point for #GVfs functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - - - - - - - - - - - - - - - The string used to obtain the volume class with g_volume_get_identifier(). - -Known volume classes include `device`, `network`, and `loop`. Other -classes may be added in the future. - -This is intended to be used by applications to classify #GVolume -instances into different sections - for example a file manager or -file chooser can use this information to show `network` volumes under -a "Network" heading and `device` volumes under a "Devices" heading. - - - - - The string used to obtain a Hal UDI with g_volume_get_identifier(). - Do not use, HAL is deprecated. - - - - - The string used to obtain a filesystem label with g_volume_get_identifier(). - - - - - The string used to obtain a NFS mount with g_volume_get_identifier(). - - - - - The string used to obtain a Unix device path with g_volume_get_identifier(). - - - - - The string used to obtain a UUID with g_volume_get_identifier(). - - - - - - - - - - - - - - - - - - - Extension point for volume monitor functionality. -See [Extending GIO][extending-gio]. - - - - - - - - - - - - Entry point for using GIO functionality. - - - Gets the default #GVfs for the system. - - - a #GVfs. - - - - - Gets the local #GVfs for the system. - - - a #GVfs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets a #GFile for @path. - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string containing a VFS path. - - - - - - Gets a #GFile for @uri. - -This operation never fails, but the returned object -might not support any I/O operation if the URI -is malformed or if the URI scheme is not supported. - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a#GVfs. - - - - a string containing a URI - - - - - - Gets a list of URI schemes supported by @vfs. - - - a %NULL-terminated array of strings. - The returned array belongs to GIO and must - not be freed or modified. - - - - - - - a #GVfs. - - - - - - Checks if the VFS is active. - - - %TRUE if construction of the @vfs was successful - and it is now active. - - - - - a #GVfs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This operation never fails, but the returned object might -not support any I/O operations if the @parse_name cannot -be parsed by the #GVfs module. - - - a #GFile for the given @parse_name. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string to be parsed by the VFS module. - - - - - - Gets a #GFile for @path. - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string containing a VFS path. - - - - - - Gets a #GFile for @uri. - -This operation never fails, but the returned object -might not support any I/O operation if the URI -is malformed or if the URI scheme is not supported. - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a#GVfs. - - - - a string containing a URI - - - - - - Gets a list of URI schemes supported by @vfs. - - - a %NULL-terminated array of strings. - The returned array belongs to GIO and must - not be freed or modified. - - - - - - - a #GVfs. - - - - - - Checks if the VFS is active. - - - %TRUE if construction of the @vfs was successful - and it is now active. - - - - - a #GVfs. - - - - - - This operation never fails, but the returned object might -not support any I/O operations if the @parse_name cannot -be parsed by the #GVfs module. - - - a #GFile for the given @parse_name. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string to be parsed by the VFS module. - - - - - - Registers @uri_func and @parse_name_func as the #GFile URI and parse name -lookup functions for URIs with a scheme matching @scheme. -Note that @scheme is registered only within the running application, as -opposed to desktop-wide as it happens with GVfs backends. - -When a #GFile is requested with an URI containing @scheme (e.g. through -g_file_new_for_uri()), @uri_func will be called to allow a custom -constructor. The implementation of @uri_func should not be blocking, and -must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). - -When g_file_parse_name() is called with a parse name obtained from such file, -@parse_name_func will be called to allow the #GFile to be created again. In -that case, it's responsibility of @parse_name_func to make sure the parse -name matches what the custom #GFile implementation returned when -g_file_get_parse_name() was previously called. The implementation of -@parse_name_func should not be blocking, and must not call -g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). - -It's an error to call this function twice with the same scheme. To unregister -a custom URI scheme, use g_vfs_unregister_uri_scheme(). - - - %TRUE if @scheme was successfully registered, or %FALSE if a handler - for @scheme already exists. - - - - - a #GVfs - - - - an URI scheme, e.g. "http" - - - - a #GVfsFileLookupFunc - - - - custom data passed to be passed to @uri_func, or %NULL - - - - function to be called when unregistering the - URI scheme, or when @vfs is disposed, to free the resources used - by the URI lookup function - - - - a #GVfsFileLookupFunc - - - - custom data passed to be passed to - @parse_name_func, or %NULL - - - - function to be called when unregistering the - URI scheme, or when @vfs is disposed, to free the resources used - by the parse name lookup function - - - - - - Unregisters the URI handler for @scheme previously registered with -g_vfs_register_uri_scheme(). - - - %TRUE if @scheme was successfully unregistered, or %FALSE if a - handler for @scheme does not exist. - - - - - a #GVfs - - - - an URI scheme, e.g. "http" - - - - - - - - - - - - - - - - - - %TRUE if construction of the @vfs was successful - and it is now active. - - - - - a #GVfs. - - - - - - - - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string containing a VFS path. - - - - - - - - - - a #GFile. - Free the returned object with g_object_unref(). - - - - - a#GVfs. - - - - a string containing a URI - - - - - - - - - - a %NULL-terminated array of strings. - The returned array belongs to GIO and must - not be freed or modified. - - - - - - - a #GVfs. - - - - - - - - - - a #GFile for the given @parse_name. - Free the returned object with g_object_unref(). - - - - - a #GVfs. - - - - a string to be parsed by the VFS module. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function type is used by g_vfs_register_uri_scheme() to make it -possible for a client to associate an URI scheme to a different #GFile -implementation. - -The client should return a reference to the new file that has been -created for @uri, or %NULL to continue with the default implementation. - - - a #GFile for @identifier. - - - - - a #GVfs - - - - the identifier to look up a #GFile for. This can either - be an URI or a parse name as returned by g_file_get_parse_name() - - - - user data passed to the function - - - - - - The #GVolume interface represents user-visible objects that can be -mounted. Note, when porting from GnomeVFS, #GVolume is the moral -equivalent of #GnomeVFSDrive. - -Mounting a #GVolume instance is an asynchronous operation. For more -information about asynchronous operations, see #GAsyncResult and -#GTask. To mount a #GVolume, first call g_volume_mount() with (at -least) the #GVolume instance, optionally a #GMountOperation object -and a #GAsyncReadyCallback. - -Typically, one will only want to pass %NULL for the -#GMountOperation if automounting all volumes when a desktop session -starts since it's not desirable to put up a lot of dialogs asking -for credentials. - -The callback will be fired when the operation has resolved (either -with success or failure), and a #GAsyncResult instance will be -passed to the callback. That callback should then call -g_volume_mount_finish() with the #GVolume instance and the -#GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_volume_mount_finish() -is called, then it will be filled with any error information. - -## Volume Identifiers # {#volume-identifier} - -It is sometimes necessary to directly access the underlying -operating system object behind a volume (e.g. for passing a volume -to an application via the commandline). For this purpose, GIO -allows to obtain an 'identifier' for the volume. There can be -different kinds of identifiers, such as Hal UDIs, filesystem labels, -traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined -strings as names for the different kinds of identifiers: -#G_VOLUME_IDENTIFIER_KIND_UUID, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. -Use g_volume_get_identifier() to obtain an identifier for a volume. - - -Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available -when the gvfs hal volume monitor is in use. Other volume monitors -will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE -identifier, which can be used to obtain a hal device by means of -libhal_manager_find_device_string_match(). - - - Checks if a volume can be ejected. - - - %TRUE if the @volume can be ejected. %FALSE otherwise - - - - - a #GVolume - - - - - - Checks if a volume can be mounted. - - - %TRUE if the @volume can be mounted. %FALSE otherwise - - - - - a #GVolume - - - - - - - - - - - - - - - - - Ejects a volume. This is an asynchronous operation, and is -finished by calling g_volume_eject_finish() with the @volume -and #GAsyncResult returned in the @callback. - Use g_volume_eject_with_operation() instead. - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - Finishes ejecting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_volume_eject_with_operation_finish() instead. - - - %TRUE, %FALSE if operation failed - - - - - pointer to a #GVolume - - - - a #GAsyncResult - - - - - - Ejects a volume. This is an asynchronous operation, and is -finished by calling g_volume_eject_with_operation_finish() with the @volume -and #GAsyncResult data returned in the @callback. - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to - avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data passed to @callback - - - - - - Finishes ejecting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the volume was successfully ejected. %FALSE otherwise - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - Gets the kinds of [identifiers][volume-identifier] that @volume has. -Use g_volume_get_identifier() to obtain the identifiers themselves. - - - a %NULL-terminated array - of strings containing kinds of identifiers. Use g_strfreev() to free. - - - - - - - a #GVolume - - - - - - Gets the activation root for a #GVolume if it is known ahead of -mount time. Returns %NULL otherwise. If not %NULL and if @volume -is mounted, then the result of g_mount_get_root() on the -#GMount object obtained from g_volume_get_mount() will always -either be equal or a prefix of what this function returns. In -other words, in code - -|[<!-- language="C" --> - GMount *mount; - GFile *mount_root - GFile *volume_activation_root; - - mount = g_volume_get_mount (volume); // mounted, so never NULL - mount_root = g_mount_get_root (mount); - volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL -]| -then the expression -|[<!-- language="C" --> - (g_file_has_prefix (volume_activation_root, mount_root) || - g_file_equal (volume_activation_root, mount_root)) -]| -will always be %TRUE. - -Activation roots are typically used in #GVolumeMonitor -implementations to find the underlying mount to shadow, see -g_mount_is_shadowed() for more details. - - - the activation root of @volume - or %NULL. Use g_object_unref() to free. - - - - - a #GVolume - - - - - - Gets the drive for the @volume. - - - a #GDrive or %NULL if @volume is not - associated with a drive. The returned object should be unreffed - with g_object_unref() when no longer needed. - - - - - a #GVolume - - - - - - Gets the icon for @volume. - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more -information about volume identifiers. - - - a newly allocated string containing the - requested identifier, or %NULL if the #GVolume - doesn't have this kind of identifier - - - - - a #GVolume - - - - the kind of identifier to return - - - - - - Gets the mount for the @volume. - - - a #GMount or %NULL if @volume isn't mounted. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the name of @volume. - - - the name for the given @volume. The returned string should - be freed with g_free() when no longer needed. - - - - - a #GVolume - - - - - - Gets the sort key for @volume, if any. - - - Sorting key for @volume or %NULL if no such key is available - - - - - a #GVolume - - - - - - Gets the symbolic icon for @volume. - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the UUID for the @volume. The reference is typically based on -the file system UUID for the volume in question and should be -considered an opaque string. Returns %NULL if there is no UUID -available. - - - the UUID for @volume or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GVolume - - - - - - Finishes mounting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - -If the mount operation succeeded, g_volume_get_mount() on @volume -is guaranteed to return the mount right after calling this -function; there's no need to listen for the 'mount-added' signal on -#GVolumeMonitor. - - - %TRUE, %FALSE if operation failed - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - Mounts a volume. This is an asynchronous operation, and is -finished by calling g_volume_mount_finish() with the @volume -and #GAsyncResult returned in the @callback. - - - - - - - a #GVolume - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - - - - - - - - - - - - Returns whether the volume should be automatically mounted. - - - %TRUE if the volume should be automatically mounted - - - - - a #GVolume - - - - - - Checks if a volume can be ejected. - - - %TRUE if the @volume can be ejected. %FALSE otherwise - - - - - a #GVolume - - - - - - Checks if a volume can be mounted. - - - %TRUE if the @volume can be mounted. %FALSE otherwise - - - - - a #GVolume - - - - - - Ejects a volume. This is an asynchronous operation, and is -finished by calling g_volume_eject_finish() with the @volume -and #GAsyncResult returned in the @callback. - Use g_volume_eject_with_operation() instead. - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - Finishes ejecting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - Use g_volume_eject_with_operation_finish() instead. - - - %TRUE, %FALSE if operation failed - - - - - pointer to a #GVolume - - - - a #GAsyncResult - - - - - - Ejects a volume. This is an asynchronous operation, and is -finished by calling g_volume_eject_with_operation_finish() with the @volume -and #GAsyncResult data returned in the @callback. - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to - avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data passed to @callback - - - - - - Finishes ejecting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - - - %TRUE if the volume was successfully ejected. %FALSE otherwise - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - Gets the kinds of [identifiers][volume-identifier] that @volume has. -Use g_volume_get_identifier() to obtain the identifiers themselves. - - - a %NULL-terminated array - of strings containing kinds of identifiers. Use g_strfreev() to free. - - - - - - - a #GVolume - - - - - - Gets the activation root for a #GVolume if it is known ahead of -mount time. Returns %NULL otherwise. If not %NULL and if @volume -is mounted, then the result of g_mount_get_root() on the -#GMount object obtained from g_volume_get_mount() will always -either be equal or a prefix of what this function returns. In -other words, in code - -|[<!-- language="C" --> - GMount *mount; - GFile *mount_root - GFile *volume_activation_root; - - mount = g_volume_get_mount (volume); // mounted, so never NULL - mount_root = g_mount_get_root (mount); - volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL -]| -then the expression -|[<!-- language="C" --> - (g_file_has_prefix (volume_activation_root, mount_root) || - g_file_equal (volume_activation_root, mount_root)) -]| -will always be %TRUE. - -Activation roots are typically used in #GVolumeMonitor -implementations to find the underlying mount to shadow, see -g_mount_is_shadowed() for more details. - - - the activation root of @volume - or %NULL. Use g_object_unref() to free. - - - - - a #GVolume - - - - - - Gets the drive for the @volume. - - - a #GDrive or %NULL if @volume is not - associated with a drive. The returned object should be unreffed - with g_object_unref() when no longer needed. - - - - - a #GVolume - - - - - - Gets the icon for @volume. - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more -information about volume identifiers. - - - a newly allocated string containing the - requested identifier, or %NULL if the #GVolume - doesn't have this kind of identifier - - - - - a #GVolume - - - - the kind of identifier to return - - - - - - Gets the mount for the @volume. - - - a #GMount or %NULL if @volume isn't mounted. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the name of @volume. - - - the name for the given @volume. The returned string should - be freed with g_free() when no longer needed. - - - - - a #GVolume - - - - - - Gets the sort key for @volume, if any. - - - Sorting key for @volume or %NULL if no such key is available - - - - - a #GVolume - - - - - - Gets the symbolic icon for @volume. - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - Gets the UUID for the @volume. The reference is typically based on -the file system UUID for the volume in question and should be -considered an opaque string. Returns %NULL if there is no UUID -available. - - - the UUID for @volume or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GVolume - - - - - - Mounts a volume. This is an asynchronous operation, and is -finished by calling g_volume_mount_finish() with the @volume -and #GAsyncResult returned in the @callback. - - - - - - - a #GVolume - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - Finishes mounting a volume. If any errors occurred during the operation, -@error will be set to contain the errors and %FALSE will be returned. - -If the mount operation succeeded, g_volume_get_mount() on @volume -is guaranteed to return the mount right after calling this -function; there's no need to listen for the 'mount-added' signal on -#GVolumeMonitor. - - - %TRUE, %FALSE if operation failed - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - Returns whether the volume should be automatically mounted. - - - %TRUE if the volume should be automatically mounted - - - - - a #GVolume - - - - - - Emitted when the volume has been changed. - - - - - - This signal is emitted when the #GVolume have been removed. If -the recipient is holding references to the object they should -release them so the object can be finalized. - - - - - - - Interface for implementing operations for mountable volumes. - - - The parent interface. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the name for the given @volume. The returned string should - be freed with g_free() when no longer needed. - - - - - a #GVolume - - - - - - - - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - - - - - the UUID for @volume or %NULL if no UUID - can be computed. - The returned string should be freed with g_free() - when no longer needed. - - - - - a #GVolume - - - - - - - - - - a #GDrive or %NULL if @volume is not - associated with a drive. The returned object should be unreffed - with g_object_unref() when no longer needed. - - - - - a #GVolume - - - - - - - - - - a #GMount or %NULL if @volume isn't mounted. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - - - - - %TRUE if the @volume can be mounted. %FALSE otherwise - - - - - a #GVolume - - - - - - - - - - %TRUE if the @volume can be ejected. %FALSE otherwise - - - - - a #GVolume - - - - - - - - - - - - - - a #GVolume - - - - flags affecting the operation - - - - a #GMountOperation or %NULL to avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - - - - - %TRUE, %FALSE if operation failed - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - - - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data that gets passed to @callback - - - - - - - - - - %TRUE, %FALSE if operation failed - - - - - pointer to a #GVolume - - - - a #GAsyncResult - - - - - - - - - - a newly allocated string containing the - requested identifier, or %NULL if the #GVolume - doesn't have this kind of identifier - - - - - a #GVolume - - - - the kind of identifier to return - - - - - - - - - - a %NULL-terminated array - of strings containing kinds of identifiers. Use g_strfreev() to free. - - - - - - - a #GVolume - - - - - - - - - - %TRUE if the volume should be automatically mounted - - - - - a #GVolume - - - - - - - - - - the activation root of @volume - or %NULL. Use g_object_unref() to free. - - - - - a #GVolume - - - - - - - - - - - - - - a #GVolume - - - - flags affecting the unmount if required for eject - - - - a #GMountOperation or %NULL to - avoid user interaction - - - - optional #GCancellable object, %NULL to ignore - - - - a #GAsyncReadyCallback, or %NULL - - - - user data passed to @callback - - - - - - - - - - %TRUE if the volume was successfully ejected. %FALSE otherwise - - - - - a #GVolume - - - - a #GAsyncResult - - - - - - - - - - Sorting key for @volume or %NULL if no such key is available - - - - - a #GVolume - - - - - - - - - - a #GIcon. - The returned object should be unreffed with g_object_unref() - when no longer needed. - - - - - a #GVolume - - - - - - - - #GVolumeMonitor is for listing the user interesting devices and volumes -on the computer. In other words, what a file selector or file manager -would show in a sidebar. - -#GVolumeMonitor is not -[thread-default-context aware][g-main-context-push-thread-default], -and so should not be used other than from the main thread, with no -thread-default-context active. - -In order to receive updates about volumes and mounts monitored through GVFS, -a main loop must be running. - - - This function should be called by any #GVolumeMonitor -implementation when a new #GMount object is created that is not -associated with a #GVolume object. It must be called just before -emitting the @mount_added signal. - -If the return value is not %NULL, the caller must associate the -returned #GVolume object with the #GMount. This involves returning -it in its g_mount_get_volume() implementation. The caller must -also listen for the "removed" signal on the returned object -and give up its reference when handling that signal - -Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), -the implementor must take a reference to @mount and return it in -its g_volume_get_mount() implemented. Also, the implementor must -listen for the "unmounted" signal on @mount and give up its -reference upon handling that signal. - -There are two main use cases for this function. - -One is when implementing a user space file system driver that reads -blocks of a block device that is already represented by the native -volume monitor (for example a CD Audio file system driver). Such -a driver will generate its own #GMount object that needs to be -associated with the #GVolume object that represents the volume. - -The other is for implementing a #GVolumeMonitor whose sole purpose -is to return #GVolume objects representing entries in the users -"favorite servers" list or similar. - Instead of using this function, #GVolumeMonitor -implementations should instead create shadow mounts with the URI of -the mount they intend to adopt. See the proxy volume monitor in -gvfs for an example of this. Also see g_mount_is_shadowed(), -g_mount_shadow() and g_mount_unshadow() functions. - - - the #GVolume object that is the parent for @mount or %NULL -if no wants to adopt the #GMount. - - - - - a #GMount object to find a parent for - - - - - - Gets the volume monitor used by gio. - - - a reference to the #GVolumeMonitor used by gio. Call - g_object_unref() when done with it. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets a list of drives connected to the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of connected #GDrive objects. - - - - - - - a #GVolumeMonitor. - - - - - - Finds a #GMount object by its UUID (see g_mount_get_uuid()) - - - a #GMount or %NULL if no such mount is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - Gets a list of the mounts on the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of #GMount objects. - - - - - - - a #GVolumeMonitor. - - - - - - Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - - - a #GVolume or %NULL if no such volume is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - Gets a list of the volumes on the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of #GVolume objects. - - - - - - - a #GVolumeMonitor. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets a list of drives connected to the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of connected #GDrive objects. - - - - - - - a #GVolumeMonitor. - - - - - - Finds a #GMount object by its UUID (see g_mount_get_uuid()) - - - a #GMount or %NULL if no such mount is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - Gets a list of the mounts on the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of #GMount objects. - - - - - - - a #GVolumeMonitor. - - - - - - Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - - - a #GVolume or %NULL if no such volume is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - Gets a list of the volumes on the system. - -The returned list should be freed with g_list_free(), after -its elements have been unreffed with g_object_unref(). - - - a #GList of #GVolume objects. - - - - - - - a #GVolumeMonitor. - - - - - - - - - - - - Emitted when a drive changes. - - - - - - the drive that changed - - - - - - Emitted when a drive is connected to the system. - - - - - - a #GDrive that was connected. - - - - - - Emitted when a drive is disconnected from the system. - - - - - - a #GDrive that was disconnected. - - - - - - Emitted when the eject button is pressed on @drive. - - - - - - the drive where the eject button was pressed - - - - - - Emitted when the stop button is pressed on @drive. - - - - - - the drive where the stop button was pressed - - - - - - Emitted when a mount is added. - - - - - - a #GMount that was added. - - - - - - Emitted when a mount changes. - - - - - - a #GMount that changed. - - - - - - May be emitted when a mount is about to be removed. - -This signal depends on the backend and is only emitted if -GIO was used to unmount. - - - - - - a #GMount that is being unmounted. - - - - - - Emitted when a mount is removed. - - - - - - a #GMount that was removed. - - - - - - Emitted when a mountable volume is added to the system. - - - - - - a #GVolume that was added. - - - - - - Emitted when mountable volume is changed. - - - - - - a #GVolume that changed. - - - - - - Emitted when a mountable volume is removed from the system. - - - - - - a #GVolume that was removed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GList of connected #GDrive objects. - - - - - - - a #GVolumeMonitor. - - - - - - - - - - a #GList of #GVolume objects. - - - - - - - a #GVolumeMonitor. - - - - - - - - - - a #GList of #GMount objects. - - - - - - - a #GVolumeMonitor. - - - - - - - - - - a #GVolume or %NULL if no such volume is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - - - - - a #GMount or %NULL if no such mount is available. - Free the returned object with g_object_unref(). - - - - - a #GVolumeMonitor. - - - - the UUID to look for - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Zlib decompression - - - - Creates a new #GZlibCompressor. - - - a new #GZlibCompressor - - - - - The format to use for the compressed data - - - - compression level (0-9), -1 for default - - - - - - Returns the #GZlibCompressor:file-info property. - - - a #GFileInfo, or %NULL - - - - - a #GZlibCompressor - - - - - - Sets @file_info in @compressor. If non-%NULL, and @compressor's -#GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, -it will be used to set the file name and modification time in -the GZIP header of the compressed data. - -Note: it is an error to call this function while a compression is in -progress; it may only be called immediately after creation of @compressor, -or after resetting it with g_converter_reset(). - - - - - - - a #GZlibCompressor - - - - a #GFileInfo - - - - - - If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is -%G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name -and modification time from the file info to the GZIP header. - - - - - - - - - - - - - - - - - Used to select the type of data format to use for #GZlibDecompressor -and #GZlibCompressor. - - deflate compression with zlib header - - - gzip file format - - - deflate compression with no header - - - - Zlib decompression - - - - Creates a new #GZlibDecompressor. - - - a new #GZlibDecompressor - - - - - The format to use for the compressed data - - - - - - Retrieves the #GFileInfo constructed from the GZIP header data -of compressed data processed by @compressor, or %NULL if @decompressor's -#GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, -or the header data was not fully processed yet, or it not present in the -data stream at all. - - - a #GFileInfo, or %NULL - - - - - a #GZlibDecompressor - - - - - - A #GFileInfo containing the information found in the GZIP header -of the data stream processed, or %NULL if the header was not yet -fully processed, is not present at all, or the compressor's -#GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. - - - - - - - - - - - - - - Checks if @action_name is valid. - -@action_name is valid if it consists only of alphanumeric characters, -plus '-' and '.'. The empty string is not a valid action name. - -It is an error to call this function with a non-utf8 @action_name. -@action_name must not be %NULL. - - - %TRUE if @action_name is valid - - - - - a potential action name - - - - - - Parses a detailed action name into its separate name and target -components. - -Detailed action names can have three formats. - -The first format is used to represent an action name with no target -value and consists of just an action name containing no whitespace -nor the characters ':', '(' or ')'. For example: "app.action". - -The second format is used to represent an action with a target value -that is a non-empty string consisting only of alphanumerics, plus '-' -and '.'. In that case, the action name and target value are -separated by a double colon ("::"). For example: -"app.action::target". - -The third format is used to represent an action with any type of -target value, including strings. The target value follows the action -name, surrounded in parens. For example: "app.action(42)". The -target value is parsed using g_variant_parse(). If a tuple-typed -value is desired, it must be specified in the same way, resulting in -two sets of parens, for example: "app.action((1,2,3))". A string -target can be specified this way as well: "app.action('target')". -For strings, this third format must be used if * target value is -empty or contains characters other than alphanumerics, '-' and '.'. - - - %TRUE if successful, else %FALSE with @error set - - - - - a detailed action name - - - - the action name - - - - the target value, or %NULL for no target - - - - - - Formats a detailed action name from @action_name and @target_value. - -It is an error to call this function with an invalid action name. - -This function is the opposite of g_action_parse_detailed_name(). -It will produce a string that can be parsed back to the @action_name -and @target_value by that function. - -See that function for the types of strings that will be printed by -this function. - - - a detailed format string - - - - - a valid action name - - - - a #GVariant target value, or %NULL - - - - - - Creates a new #GAppInfo from the given information. - -Note that for @commandline, the quoting rules of the Exec key of the -[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) -are applied. For example, if the @commandline contains -percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. - - - new #GAppInfo for given command. - - - - - the commandline to use - - - - the application name, or %NULL to use @commandline - - - - flags that can specify details of the created #GAppInfo - - - - - - Gets a list of all of the applications currently registered -on this system. - -For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. - - - a newly allocated #GList of references to #GAppInfos. - - - - - - - Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Gets the default #GAppInfo for a given content type. - - - #GAppInfo for given @content_type or - %NULL on error. - - - - - the content type to find a #GAppInfo for - - - - if %TRUE, the #GAppInfo is expected to - support URIs - - - - - - Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". - - - #GAppInfo for given @uri_scheme or %NULL on error. - - - - - a string containing a URI scheme. - - - - - - Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. -Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. - - - #GList of #GAppInfos - for given @content_type or %NULL on error. - - - - - - - the content type to find a #GAppInfo for - - - - - - Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. - -The D-Bus–activated applications don't have to be started if your application -terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. - - - %TRUE on success, %FALSE on error. - - - - - the uri to show - - - - an optional #GAppLaunchContext - - - - - - Async version of g_app_info_launch_default_for_uri(). - -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. - -This is also useful if you want to be sure that the D-Bus–activated -applications are really started before termination and if you are interested -in receiving error information from their activation. - - - - - - - the uri to show - - - - an optional #GAppLaunchContext - - - - a #GCancellable - - - - a #GAsyncReadyCallback to call when the request is done - - - - data to pass to @callback - - - - - - Finishes an asynchronous launch-default-for-uri operation. - - - %TRUE if the launch was successful, %FALSE if @error is set - - - - - a #GAsyncResult - - - - - - Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). - - - - - - - a content type - - - - - - Helper function for constructing #GAsyncInitable object. This is -similar to g_object_newv() but also initializes the object asynchronously. - -When the initialization is finished, @callback will be called. You can -then call g_async_initable_new_finish() to get the new object and check -for any errors. - Use g_object_new_with_properties() and -g_async_initable_init_async() instead. See #GParameter for more information. - - - - - - - a #GType supporting #GAsyncInitable. - - - - the number of parameters in @parameters - - - - the parameters to use to construct the object - - - - the [I/O priority][io-priority] of the operation - - - - optional #GCancellable object, %NULL to ignore. - - - - a #GAsyncReadyCallback to call when the initialization is - finished - - - - the data to pass to callback function - - - - - - Asynchronously connects to the message bus specified by @bus_type. - -When the operation is finished, @callback will be invoked. You can -then call g_bus_get_finish() to get the result of the operation. - -This is an asynchronous failable function. See g_bus_get_sync() for -the synchronous version. - - - - - - - a #GBusType - - - - a #GCancellable or %NULL - - - - a #GAsyncReadyCallback to call when the request is satisfied - - - - the data to pass to @callback - - - - - - Finishes an operation started with g_bus_get(). - -The returned object is a singleton, that is, shared with other -callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the -event that you need a private message bus connection, use -g_dbus_address_get_for_bus_sync() and -g_dbus_connection_new_for_address(). - -Note that the returned #GDBusConnection object will (usually) have -the #GDBusConnection:exit-on-close property set to %TRUE. - - - a #GDBusConnection or %NULL if @error is set. - Free with g_object_unref(). - - - - - a #GAsyncResult obtained from the #GAsyncReadyCallback passed - to g_bus_get() - - - - - - Synchronously connects to the message bus specified by @bus_type. -Note that the returned object may shared with other callers, -e.g. if two separate parts of a process calls this function with -the same @bus_type, they will share the same object. - -This is a synchronous failable function. See g_bus_get() and -g_bus_get_finish() for the asynchronous version. - -The returned object is a singleton, that is, shared with other -callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the -event that you need a private message bus connection, use -g_dbus_address_get_for_bus_sync() and -g_dbus_connection_new_for_address(). - -Note that the returned #GDBusConnection object will (usually) have -the #GDBusConnection:exit-on-close property set to %TRUE. - - - a #GDBusConnection or %NULL if @error is set. - Free with g_object_unref(). - - - - - a #GBusType - - - - a #GCancellable or %NULL - - - - - - Starts acquiring @name on the bus specified by @bus_type and calls -@name_acquired_handler and @name_lost_handler when the name is -acquired respectively lost. Callbacks will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this function from. - -You are guaranteed that one of the @name_acquired_handler and @name_lost_handler -callbacks will be invoked after calling this function - there are three -possible cases: - -- @name_lost_handler with a %NULL connection (if a connection to the bus - can't be made). - -- @bus_acquired_handler then @name_lost_handler (if the name can't be - obtained) - -- @bus_acquired_handler then @name_acquired_handler (if the name was - obtained). - -When you are done owning the name, just call g_bus_unown_name() -with the owner id this function returns. - -If the name is acquired or lost (for example another application -could acquire the name if you allow replacement or the application -currently owning the name exits), the handlers are also invoked. -If the #GDBusConnection that is used for attempting to own the name -closes, then @name_lost_handler is invoked since it is no longer -possible for other processes to access the process. - -You cannot use g_bus_own_name() several times for the same name (unless -interleaved with calls to g_bus_unown_name()) - only the first call -will work. - -Another guarantee is that invocations of @name_acquired_handler -and @name_lost_handler are guaranteed to alternate; that -is, if @name_acquired_handler is invoked then you are -guaranteed that the next time one of the handlers is invoked, it -will be @name_lost_handler. The reverse is also true. - -If you plan on exporting objects (using e.g. -g_dbus_connection_register_object()), note that it is generally too late -to export the objects in @name_acquired_handler. Instead, you can do this -in @bus_acquired_handler since you are guaranteed that this will run -before @name is requested from the bus. - -This behavior makes it very simple to write applications that wants -to [own names][gdbus-owning-names] and export objects. -Simply register objects to be exported in @bus_acquired_handler and -unregister the objects (if any) in @name_lost_handler. - - - an identifier (never 0) that can be used with - g_bus_unown_name() to stop owning the name. - - - - - the type of bus to own a name on - - - - the well-known name to own - - - - a set of flags from the #GBusNameOwnerFlags enumeration - - - - handler to invoke when connected to the bus of type @bus_type or %NULL - - - - handler to invoke when @name is acquired or %NULL - - - - handler to invoke when @name is lost or %NULL - - - - user data to pass to handlers - - - - function for freeing @user_data or %NULL - - - - - - Like g_bus_own_name() but takes a #GDBusConnection instead of a -#GBusType. - - - an identifier (never 0) that can be used with - g_bus_unown_name() to stop owning the name - - - - - a #GDBusConnection - - - - the well-known name to own - - - - a set of flags from the #GBusNameOwnerFlags enumeration - - - - handler to invoke when @name is acquired or %NULL - - - - handler to invoke when @name is lost or %NULL - - - - user data to pass to handlers - - - - function for freeing @user_data or %NULL - - - - - - Version of g_bus_own_name_on_connection() using closures instead of -callbacks for easier binding in other languages. - - - an identifier (never 0) that can be used with - g_bus_unown_name() to stop owning the name. - - - - - a #GDBusConnection - - - - the well-known name to own - - - - a set of flags from the #GBusNameOwnerFlags enumeration - - - - #GClosure to invoke when @name is - acquired or %NULL - - - - #GClosure to invoke when @name is lost - or %NULL - - - - - - Version of g_bus_own_name() using closures instead of callbacks for -easier binding in other languages. - - - an identifier (never 0) that can be used with - g_bus_unown_name() to stop owning the name. - - - - - the type of bus to own a name on - - - - the well-known name to own - - - - a set of flags from the #GBusNameOwnerFlags enumeration - - - - #GClosure to invoke when connected to - the bus of type @bus_type or %NULL - - - - #GClosure to invoke when @name is - acquired or %NULL - - - - #GClosure to invoke when @name is lost or - %NULL - - - - - - Stops owning a name. - -Note that there may still be D-Bus traffic to process (relating to owning -and unowning the name) in the current thread-default #GMainContext after -this function has returned. You should continue to iterate the #GMainContext -until the #GDestroyNotify function passed to g_bus_own_name() is called, in -order to avoid memory leaks through callbacks queued on the #GMainContext -after it’s stopped being iterated. - - - - - - - an identifier obtained from g_bus_own_name() - - - - - - Stops watching a name. - -Note that there may still be D-Bus traffic to process (relating to watching -and unwatching the name) in the current thread-default #GMainContext after -this function has returned. You should continue to iterate the #GMainContext -until the #GDestroyNotify function passed to g_bus_watch_name() is called, in -order to avoid memory leaks through callbacks queued on the #GMainContext -after it’s stopped being iterated. - - - - - - - An identifier obtained from g_bus_watch_name() - - - - - - Starts watching @name on the bus specified by @bus_type and calls -@name_appeared_handler and @name_vanished_handler when the name is -known to have an owner respectively known to lose its -owner. Callbacks will be invoked in the -[thread-default main context][g-main-context-push-thread-default] -of the thread you are calling this function from. - -You are guaranteed that one of the handlers will be invoked after -calling this function. When you are done watching the name, just -call g_bus_unwatch_name() with the watcher id this function -returns. - -If the name vanishes or appears (for example the application owning -the name could restart), the handlers are also invoked. If the -#GDBusConnection that is used for watching the name disconnects, then -@name_vanished_handler is invoked since it is no longer -possible to access the name. - -Another guarantee is that invocations of @name_appeared_handler -and @name_vanished_handler are guaranteed to alternate; that -is, if @name_appeared_handler is invoked then you are -guaranteed that the next time one of the handlers is invoked, it -will be @name_vanished_handler. The reverse is also true. - -This behavior makes it very simple to write applications that want -to take action when a certain [name exists][gdbus-watching-names]. -Basically, the application should create object proxies in -@name_appeared_handler and destroy them again (if any) in -@name_vanished_handler. - - - An identifier (never 0) that can be used with -g_bus_unwatch_name() to stop watching the name. - - - - - The type of bus to watch a name on. - - - - The name (well-known or unique) to watch. - - - - Flags from the #GBusNameWatcherFlags enumeration. - - - - Handler to invoke when @name is known to exist or %NULL. - - - - Handler to invoke when @name is known to not exist or %NULL. - - - - User data to pass to handlers. - - - - Function for freeing @user_data or %NULL. - - - - - - Like g_bus_watch_name() but takes a #GDBusConnection instead of a -#GBusType. - - - An identifier (never 0) that can be used with -g_bus_unwatch_name() to stop watching the name. - - - - - A #GDBusConnection. - - - - The name (well-known or unique) to watch. - - - - Flags from the #GBusNameWatcherFlags enumeration. - - - - Handler to invoke when @name is known to exist or %NULL. - - - - Handler to invoke when @name is known to not exist or %NULL. - - - - User data to pass to handlers. - - - - Function for freeing @user_data or %NULL. - - - - - - Version of g_bus_watch_name_on_connection() using closures instead of callbacks for -easier binding in other languages. - - - An identifier (never 0) that can be used with -g_bus_unwatch_name() to stop watching the name. - - - - - A #GDBusConnection. - - - - The name (well-known or unique) to watch. - - - - Flags from the #GBusNameWatcherFlags enumeration. - - - - #GClosure to invoke when @name is known -to exist or %NULL. - - - - #GClosure to invoke when @name is known -to not exist or %NULL. - - - - - - Version of g_bus_watch_name() using closures instead of callbacks for -easier binding in other languages. - - - An identifier (never 0) that can be used with -g_bus_unwatch_name() to stop watching the name. - - - - - The type of bus to watch a name on. - - - - The name (well-known or unique) to watch. - - - - Flags from the #GBusNameWatcherFlags enumeration. - - - - #GClosure to invoke when @name is known -to exist or %NULL. - - - - #GClosure to invoke when @name is known -to not exist or %NULL. - - - - - - Checks if a content type can be executable. Note that for instance -things like text files can be executables (i.e. scripts and batch files). - - - %TRUE if the file type corresponds to a type that - can be executable, %FALSE otherwise. - - - - - a content type string - - - - - - Compares two content types for equality. - - - %TRUE if the two strings are identical or equivalent, - %FALSE otherwise. - - - - - a content type string - - - - a content type string - - - - - - Tries to find a content type based on the mime type name. - - - Newly allocated string with content type or - %NULL. Free with g_free() - - - - - a mime type string - - - - - - Gets the human readable description of the content type. - - - a short description of the content type @type. Free the - returned string with g_free() - - - - - a content type string - - - - - - Gets the generic icon name for a content type. - -See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on the generic icon name. - - - the registered generic icon name for the given @type, - or %NULL if unknown. Free with g_free() - - - - - a content type string - - - - - - Gets the icon for a content type. - - - #GIcon corresponding to the content type. Free the returned - object with g_object_unref() - - - - - a content type string - - - - - - Get the list of directories which MIME data is loaded from. See -g_content_type_set_mime_dirs() for details. - - - %NULL-terminated list of - directories to load MIME data from, including any `mime/` subdirectory, - and with the first directory to try listed first - - - - - - - Gets the mime type for the content type, if one is registered. - - - the registered mime type for the - given @type, or %NULL if unknown; free with g_free(). - - - - - a content type string - - - - - - Gets the symbolic icon for a content type. - - - symbolic #GIcon corresponding to the content type. - Free the returned object with g_object_unref() - - - - - a content type string - - - - - - Guesses the content type based on example data. If the function is -uncertain, @result_uncertain will be set to %TRUE. Either @filename -or @data may be %NULL, in which case the guess will be based solely -on the other argument. - - - a string indicating a guessed content type for the - given data. Free with g_free() - - - - - a string, or %NULL - - - - a stream of data, or %NULL - - - - - - the size of @data - - - - return location for the certainty - of the result, or %NULL - - - - - - Tries to guess the type of the tree with root @root, by -looking at the files it contains. The result is an array -of content types, with the best guess coming first. - -The types returned all have the form x-content/foo, e.g. -x-content/audio-cdda (for audio CDs) or x-content/image-dcf -(for a camera memory card). See the -[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) -specification for more on x-content types. - -This function is useful in the implementation of -g_mount_guess_content_type(). - - - an %NULL-terminated - array of zero or more content types. Free with g_strfreev() - - - - - - - the root of the tree to guess a type for - - - - - - Determines if @type is a subset of @supertype. - - - %TRUE if @type is a kind of @supertype, - %FALSE otherwise. - - - - - a content type string - - - - a content type string - - - - - - Determines if @type is a subset of @mime_type. -Convenience wrapper around g_content_type_is_a(). - - - %TRUE if @type is a kind of @mime_type, - %FALSE otherwise. - - - - - a content type string - - - - a mime type string - - - - - - Checks if the content type is the generic "unknown" type. -On UNIX this is the "application/octet-stream" mimetype, -while on win32 it is "*" and on OSX it is a dynamic type -or octet-stream. - - - %TRUE if the type is the unknown type. - - - - - a content type string - - - - - - Set the list of directories used by GIO to load the MIME database. -If @dirs is %NULL, the directories used are the default: - - - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` - - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` - -This function is intended to be used when writing tests that depend on -information stored in the MIME database, in order to control the data. - -Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they -depend on the system’s MIME database, you should call this function -with @dirs set to %NULL before calling g_test_init(), for instance: - -|[<!-- language="C" --> - // Load MIME data from the system - g_content_type_set_mime_dirs (NULL); - // Isolate the environment - g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); - - … - - return g_test_run (); -]| - - - - - - - %NULL-terminated list of - directories to load MIME data from, including any `mime/` subdirectory, - and with the first directory to try listed first - - - - - - - - Gets a list of strings containing all the registered content types -known to the system. The list and its data should be freed using -`g_list_free_full (list, g_free)`. - - - list of the registered - content types - - - - - - - Escape @string so it can appear in a D-Bus address as the value -part of a key-value pair. - -For instance, if @string is `/run/bus-for-:0`, -this function would return `/run/bus-for-%3A0`, -which could be used in a D-Bus address like -`unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. - - - a copy of @string with all - non-optionally-escaped bytes escaped - - - - - an unescaped string to be included in a D-Bus address - as the value in a key-value pair - - - - - - Synchronously looks up the D-Bus address for the well-known message -bus instance specified by @bus_type. This may involve using various -platform specific mechanisms. - -The returned address will be in the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - - - a valid D-Bus address string for @bus_type or - %NULL if @error is set - - - - - a #GBusType - - - - a #GCancellable or %NULL - - - - - - Asynchronously connects to an endpoint specified by @address and -sets up the connection so it is in a state to run the client-side -of the D-Bus authentication conversation. @address must be in the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -When the operation is finished, @callback will be invoked. You can -then call g_dbus_address_get_stream_finish() to get the result of -the operation. - -This is an asynchronous failable function. See -g_dbus_address_get_stream_sync() for the synchronous version. - - - - - - - A valid D-Bus address. - - - - A #GCancellable or %NULL. - - - - A #GAsyncReadyCallback to call when the request is satisfied. - - - - Data to pass to @callback. - - - - - - Finishes an operation started with g_dbus_address_get_stream(). - - - A #GIOStream or %NULL if @error is set. - - - - - A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - - - - %NULL or return location to store the GUID extracted from @address, if any. - - - - - - Synchronously connects to an endpoint specified by @address and -sets up the connection so it is in a state to run the client-side -of the D-Bus authentication conversation. @address must be in the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -This is a synchronous failable function. See -g_dbus_address_get_stream() for the asynchronous version. - - - A #GIOStream or %NULL if @error is set. - - - - - A valid D-Bus address. - - - - %NULL or return location to store the GUID extracted from @address, if any. - - - - A #GCancellable or %NULL. - - - - - - Looks up the value of an annotation. - -The cost of this function is O(n) in number of annotations. - - - The value or %NULL if not found. Do not free, it is owned by @annotations. - - - - - A %NULL-terminated array of annotations or %NULL. - - - - - - The name of the annotation to look up. - - - - - - Creates a D-Bus error name to use for @error. If @error matches -a registered error (cf. g_dbus_error_register_error()), the corresponding -D-Bus error name will be returned. - -Otherwise the a name of the form -`org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` -will be used. This allows other GDBus applications to map the error -on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). - -This function is typically only used in object mappings to put a -#GError on the wire. Regular applications should not use it. - - - A D-Bus error name (never %NULL). Free with g_free(). - - - - - A #GError. - - - - - - Gets the D-Bus error name used for @error, if any. - -This function is guaranteed to return a D-Bus error name for all -#GErrors returned from functions handling remote method calls -(e.g. g_dbus_connection_call_finish()) unless -g_dbus_error_strip_remote_error() has been used on @error. - - - an allocated string or %NULL if the D-Bus error name - could not be found. Free with g_free(). - - - - - a #GError - - - - - - Checks if @error represents an error received via D-Bus from a remote peer. If so, -use g_dbus_error_get_remote_error() to get the name of the error. - - - %TRUE if @error represents an error from a remote peer, -%FALSE otherwise. - - - - - A #GError. - - - - - - Creates a #GError based on the contents of @dbus_error_name and -@dbus_error_message. - -Errors registered with g_dbus_error_register_error() will be looked -up using @dbus_error_name and if a match is found, the error domain -and code is used. Applications can use g_dbus_error_get_remote_error() -to recover @dbus_error_name. - -If a match against a registered error is not found and the D-Bus -error name is in a form as returned by g_dbus_error_encode_gerror() -the error domain and code encoded in the name is used to -create the #GError. Also, @dbus_error_name is added to the error message -such that it can be recovered with g_dbus_error_get_remote_error(). - -Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR -in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is -added to the error message such that it can be recovered with -g_dbus_error_get_remote_error(). - -In all three cases, @dbus_error_name can always be recovered from the -returned #GError using the g_dbus_error_get_remote_error() function -(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). - -This function is typically only used in object mappings to prepare -#GError instances for applications. Regular applications should not use -it. - - - An allocated #GError. Free with g_error_free(). - - - - - D-Bus error name. - - - - D-Bus error message. - - - - - - - - - - - Creates an association to map between @dbus_error_name and -#GErrors specified by @error_domain and @error_code. - -This is typically done in the routine that returns the #GQuark for -an error domain. - - - %TRUE if the association was created, %FALSE if it already -exists. - - - - - A #GQuark for an error domain. - - - - An error code. - - - - A D-Bus error name. - - - - - - Helper function for associating a #GError error domain with D-Bus error names. - - - - - - - The error domain name. - - - - A pointer where to store the #GQuark. - - - - A pointer to @num_entries #GDBusErrorEntry struct items. - - - - - - Number of items to register. - - - - - - Looks for extra information in the error message used to recover -the D-Bus error name and strips it if found. If stripped, the -message field in @error will correspond exactly to what was -received on the wire. - -This is typically used when presenting errors to the end user. - - - %TRUE if information was stripped, %FALSE otherwise. - - - - - A #GError. - - - - - - Destroys an association previously set up with g_dbus_error_register_error(). - - - %TRUE if the association was destroyed, %FALSE if it wasn't found. - - - - - A #GQuark for an error domain. - - - - An error code. - - - - A D-Bus error name. - - - - - - Generate a D-Bus GUID that can be used with -e.g. g_dbus_connection_new(). - -See the D-Bus specification regarding what strings are valid D-Bus -GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). - - - A valid D-Bus GUID. Free with g_free(). - - - - - Converts a #GValue to a #GVariant of the type indicated by the @type -parameter. - -The conversion is using the following rules: - -- #G_TYPE_STRING: 's', 'o', 'g' or 'ay' -- #G_TYPE_STRV: 'as', 'ao' or 'aay' -- #G_TYPE_BOOLEAN: 'b' -- #G_TYPE_UCHAR: 'y' -- #G_TYPE_INT: 'i', 'n' -- #G_TYPE_UINT: 'u', 'q' -- #G_TYPE_INT64 'x' -- #G_TYPE_UINT64: 't' -- #G_TYPE_DOUBLE: 'd' -- #G_TYPE_VARIANT: Any #GVariantType - -This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type -is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType -(including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not -in the table above. - -Note that if @gvalue is of type #G_TYPE_VARIANT and its value is -%NULL, the empty #GVariant instance (never %NULL) for @type is -returned (e.g. 0 for scalar types, the empty string for string types, -'/' for object path types, the empty array for any array type and so on). - -See the g_dbus_gvariant_to_gvalue() function for how to convert a -#GVariant to a #GValue. - - - A #GVariant (never floating) of #GVariantType @type holding - the data from @gvalue or %NULL in case of failure. Free with - g_variant_unref(). - - - - - A #GValue to convert to a #GVariant - - - - A #GVariantType - - - - - - Converts a #GVariant to a #GValue. If @value is floating, it is consumed. - -The rules specified in the g_dbus_gvalue_to_gvariant() function are -used - this function is essentially its reverse form. So, a #GVariant -containing any basic or string array type will be converted to a #GValue -containing a basic value or string array. Any other #GVariant (handle, -variant, tuple, dict entry) will be converted to a #GValue containing that -#GVariant. - -The conversion never fails - a valid #GValue is always returned in -@out_gvalue. - - - - - - - A #GVariant. - - - - Return location pointing to a zero-filled (uninitialized) #GValue. - - - - - - Checks if @string is a -[D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - -This doesn't check if @string is actually supported by #GDBusServer -or #GDBusConnection - use g_dbus_is_supported_address() to do more -checks. - - - %TRUE if @string is a valid D-Bus address, %FALSE otherwise. - - - - - A string. - - - - - - Checks if @string is a D-Bus GUID. - -See the D-Bus specification regarding what strings are valid D-Bus -GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). - - - %TRUE if @string is a guid, %FALSE otherwise. - - - - - The string to check. - - - - - - Checks if @string is a valid D-Bus interface name. - - - %TRUE if valid, %FALSE otherwise. - - - - - The string to check. - - - - - - Checks if @string is a valid D-Bus member (e.g. signal or method) name. - - - %TRUE if valid, %FALSE otherwise. - - - - - The string to check. - - - - - - Checks if @string is a valid D-Bus bus name (either unique or well-known). - - - %TRUE if valid, %FALSE otherwise. - - - - - The string to check. - - - - - - Like g_dbus_is_address() but also checks if the library supports the -transports in @string and that key/value pairs for each transport -are valid. See the specification of the -[D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - - - %TRUE if @string is a valid D-Bus address that is -supported by this library, %FALSE if @error is set. - - - - - A string. - - - - - - Checks if @string is a valid D-Bus unique bus name. - - - %TRUE if valid, %FALSE otherwise. - - - - - The string to check. - - - - - - Creates a new #GDtlsClientConnection wrapping @base_socket which is -assumed to communicate with the server identified by @server_identity. - - - the new - #GDtlsClientConnection, or %NULL on error - - - - - the #GDatagramBased to wrap - - - - the expected identity of the server - - - - - - Creates a new #GDtlsServerConnection wrapping @base_socket. - - - the new - #GDtlsServerConnection, or %NULL on error - - - - - the #GDatagramBased to wrap - - - - the default server certificate, or %NULL - - - - - - Creates a #GFile with the given argument from the command line. -The value of @arg can be either a URI, an absolute path or a -relative path resolved relative to the current working directory. -This operation never fails, but the returned object might not -support any I/O operation if @arg points to a malformed path. - -Note that on Windows, this function expects its argument to be in -UTF-8 -- not the system code page. This means that you -should not use this function with string from argv as it is passed -to main(). g_win32_get_command_line() will return a UTF-8 version of -the commandline. #GApplication also uses UTF-8 but -g_application_command_line_create_file_for_arg() may be more useful -for you there. It is also always possible to use this function with -#GOptionContext arguments of type %G_OPTION_ARG_FILENAME. - - - a new #GFile. - Free the returned object with g_object_unref(). - - - - - a command line string - - - - - - Creates a #GFile with the given argument from the command line. - -This function is similar to g_file_new_for_commandline_arg() except -that it allows for passing the current working directory as an -argument instead of using the current working directory of the -process. - -This is useful if the commandline argument was given in a context -other than the invocation of the current process. - -See also g_application_command_line_create_file_for_arg(). - - - a new #GFile - - - - - a command line string - - - - the current working directory of the commandline - - - - - - Constructs a #GFile for a given path. This operation never -fails, but the returned object might not support any I/O -operation if @path is malformed. - - - a new #GFile for the given @path. - Free the returned object with g_object_unref(). - - - - - a string containing a relative or absolute path. - The string must be encoded in the glib filename encoding. - - - - - - Constructs a #GFile for a given URI. This operation never -fails, but the returned object might not support any I/O -operation if @uri is malformed or if the uri type is -not supported. - - - a new #GFile for the given @uri. - Free the returned object with g_object_unref(). - - - - - a UTF-8 string containing a URI - - - - - - Opens a file in the preferred directory for temporary files (as -returned by g_get_tmp_dir()) and returns a #GFile and -#GFileIOStream pointing to it. - -@tmpl should be a string in the GLib file name encoding -containing a sequence of six 'X' characters, and containing no -directory components. If it is %NULL, a default template is used. - -Unlike the other #GFile constructors, this will return %NULL if -a temporary file could not be created. - - - a new #GFile. - Free the returned object with g_object_unref(). - - - - - Template for the file - name, as in g_file_open_tmp(), or %NULL for a default template - - - - on return, a #GFileIOStream for the created file - - - - - - Constructs a #GFile with the given @parse_name (i.e. something -given by g_file_get_parse_name()). This operation never fails, -but the returned object might not support any I/O operation if -the @parse_name cannot be parsed. - - - a new #GFile. - - - - - a file name or path to be parsed - - - - - - Deserializes a #GIcon previously serialized using g_icon_serialize(). - - - a #GIcon, or %NULL when deserialization fails. - - - - - a #GVariant created with g_icon_serialize() - - - - - - Gets a hash for an icon. - - - a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. - - - - - #gconstpointer to an icon object. - - - - - - Generate a #GIcon instance from @str. This function can fail if -@str is not valid - see g_icon_to_string() for discussion. - -If your application or library provides one or more #GIcon -implementations you need to ensure that each #GType is registered -with the type system prior to calling g_icon_new_for_string(). - - - An object implementing the #GIcon - interface or %NULL if @error is set. - - - - - A string obtained via g_icon_to_string(). - - - - - - Helper function for constructing #GInitable object. This is -similar to g_object_newv() but also initializes the object -and returns %NULL, setting an error on failure. - Use g_object_new_with_properties() and -g_initable_init() instead. See #GParameter for more information. - - - a newly allocated - #GObject, or %NULL on error - - - - - a #GType supporting #GInitable. - - - - the number of parameters in @parameters - - - - the parameters to use to construct the object - - - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Converts errno.h error codes into GIO error codes. The fallback -value %G_IO_ERROR_FAILED is returned for error codes not currently -handled (but note that future GLib releases may return a more -specific value instead). - -As %errno is global and may be modified by intermediate function -calls, you should save its value as soon as the call which sets it - - - #GIOErrorEnum value for the given errno.h error number. - - - - - Error number as defined in errno.h. - - - - - - Gets the GIO Error Quark. - - a #GQuark. - - - - - Registers @type as extension for the extension point with name -@extension_point_name. - -If @type has already been registered as an extension for this -extension point, the existing #GIOExtension object is returned. - - - a #GIOExtension object for #GType - - - - - the name of the extension point - - - - the #GType to register as extension - - - - the name for the extension - - - - the priority for the extension - - - - - - Looks up an existing extension point. - - - the #GIOExtensionPoint, or %NULL if there - is no registered extension point with the given name. - - - - - the name of the extension point - - - - - - Registers an extension point. - - - the new #GIOExtensionPoint. This object is - owned by GIO and should not be freed. - - - - - The name of the extension point - - - - - - Loads all the modules in the specified directory. - -If don't require all modules to be initialized (and thus registering -all gtypes) then you can use g_io_modules_scan_all_in_directory() -which allows delayed/lazy loading of modules. - - - a list of #GIOModules loaded - from the directory, - All the modules are loaded into memory, if you want to - unload them (enabling on-demand loading) you must call - g_type_module_unuse() on all the modules. Free the list - with g_list_free(). - - - - - - - pathname for a directory containing modules - to load. - - - - - - Loads all the modules in the specified directory. - -If don't require all modules to be initialized (and thus registering -all gtypes) then you can use g_io_modules_scan_all_in_directory() -which allows delayed/lazy loading of modules. - - - a list of #GIOModules loaded - from the directory, - All the modules are loaded into memory, if you want to - unload them (enabling on-demand loading) you must call - g_type_module_unuse() on all the modules. Free the list - with g_list_free(). - - - - - - - pathname for a directory containing modules - to load. - - - - a scope to use when scanning the modules. - - - - - - Scans all the modules in the specified directory, ensuring that -any extension point implemented by a module is registered. - -This may not actually load and initialize all the types in each -module, some modules may be lazily loaded and initialized when -an extension point it implementes is used with e.g. -g_io_extension_point_get_extensions() or -g_io_extension_point_get_extension_by_name(). - -If you need to guarantee that all types are loaded in all the modules, -use g_io_modules_load_all_in_directory(). - - - - - - - pathname for a directory containing modules - to scan. - - - - - - Scans all the modules in the specified directory, ensuring that -any extension point implemented by a module is registered. - -This may not actually load and initialize all the types in each -module, some modules may be lazily loaded and initialized when -an extension point it implementes is used with e.g. -g_io_extension_point_get_extensions() or -g_io_extension_point_get_extension_by_name(). - -If you need to guarantee that all types are loaded in all the modules, -use g_io_modules_load_all_in_directory(). - - - - - - - pathname for a directory containing modules - to scan. - - - - a scope to use when scanning the modules - - - - - - Cancels all cancellable I/O jobs. - -A job is cancellable if a #GCancellable was passed into -g_io_scheduler_push_job(). - You should never call this function, since you don't -know how other libraries in your program might be making use of -gioscheduler. - - - - - - - Schedules the I/O job to run in another thread. - -@notify will be called on @user_data after @job_func has returned, -regardless whether the job was cancelled or has run to completion. - -If @cancellable is not %NULL, it can be used to cancel the I/O job -by calling g_cancellable_cancel() or by calling -g_io_scheduler_cancel_all_jobs(). - use #GThreadPool or g_task_run_in_thread() - - - - - - - a #GIOSchedulerJobFunc. - - - - data to pass to @job_func - - - - a #GDestroyNotify for @user_data, or %NULL - - - - the [I/O priority][io-priority] -of the request. - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Creates a keyfile-backed #GSettingsBackend. - -The filename of the keyfile to use is given by @filename. - -All settings read to or written from the backend must fall under the -path given in @root_path (which must start and end with a slash and -not contain two consecutive slashes). @root_path may be "/". - -If @root_group is non-%NULL then it specifies the name of the keyfile -group used for keys that are written directly below @root_path. For -example, if @root_path is "/apps/example/" and @root_group is -"toplevel", then settings the key "/apps/example/enabled" to a value -of %TRUE will cause the following to appear in the keyfile: - -|[ - [toplevel] - enabled=true -]| - -If @root_group is %NULL then it is not permitted to store keys -directly below the @root_path. - -For keys not stored directly below @root_path (ie: in a sub-path), -the name of the subpath (with the final slash stripped) is used as -the name of the keyfile group. To continue the example, if -"/apps/example/profiles/default/font-size" were set to -12 then the following would appear in the keyfile: - -|[ - [profiles/default] - font-size=12 -]| - -The backend will refuse writes (and return writability as being -%FALSE) for keys outside of @root_path and, in the event that -@root_group is %NULL, also for keys directly under @root_path. -Writes will also be refused if the backend detects that it has the -inability to rewrite the keyfile (ie: the containing directory is not -writable). - -There is no checking done for your key namespace clashing with the -syntax of the key file format. For example, if you have '[' or ']' -characters in your path names or '=' in your key names you may be in -trouble. - -The backend reads default values from a keyfile called `defaults` in -the directory specified by the #GKeyfileSettingsBackend:defaults-dir property, -and a list of locked keys from a text file with the name `locks` in -the same location. - - - a keyfile-backed #GSettingsBackend - - - - - the filename of the keyfile - - - - the path under which all settings keys appear - - - - the group name corresponding to - @root_path, or %NULL - - - - - - Gets a reference to the default #GMemoryMonitor for the system. - - - a new reference to the default #GMemoryMonitor - - - - - Creates a memory-backed #GSettingsBackend. - -This backend allows changes to settings, but does not write them -to any backing storage, so the next time you run your application, -the memory backend will start out with the default values again. - - - a newly created #GSettingsBackend - - - - - Gets the default #GNetworkMonitor for the system. - - - a #GNetworkMonitor - - - - - Initializes the platform networking libraries (eg, on Windows, this -calls WSAStartup()). GLib will call this itself if it is needed, so -you only need to call it if you directly call system networking -functions (without calling any GLib networking functions first). - - - - - - - Creates a readonly #GSettingsBackend. - -This backend does not allow changes to settings, so all settings -will always have their default values. - - - a newly created #GSettingsBackend - - - - - Utility method for #GPollableInputStream and #GPollableOutputStream -implementations. Creates a new #GSource that expects a callback of -type #GPollableSourceFunc. The new source does not actually do -anything on its own; use g_source_add_child_source() to add other -sources to it to cause it to trigger. - - - the new #GSource. - - - - - the stream associated with the new source - - - - - - Utility method for #GPollableInputStream and #GPollableOutputStream -implementations. Creates a new #GSource, as with -g_pollable_source_new(), but also attaching @child_source (with a -dummy callback), and @cancellable, if they are non-%NULL. - - - the new #GSource. - - - - - the stream associated with the - new source - - - - optional child source to attach - - - - optional #GCancellable to attach - - - - - - Tries to read from @stream, as with g_input_stream_read() (if -@blocking is %TRUE) or g_pollable_input_stream_read_nonblocking() -(if @blocking is %FALSE). This can be used to more easily share -code between blocking and non-blocking implementations of a method. - -If @blocking is %FALSE, then @stream must be a -#GPollableInputStream for which g_pollable_input_stream_can_poll() -returns %TRUE, or else the behavior is undefined. If @blocking is -%TRUE, then @stream does not need to be a #GPollableInputStream. - - - the number of bytes read, or -1 on error. - - - - - a #GInputStream - - - - a buffer to - read data into - - - - - - the number of bytes to read - - - - whether to do blocking I/O - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tries to write to @stream, as with g_output_stream_write() (if -@blocking is %TRUE) or g_pollable_output_stream_write_nonblocking() -(if @blocking is %FALSE). This can be used to more easily share -code between blocking and non-blocking implementations of a method. - -If @blocking is %FALSE, then @stream must be a -#GPollableOutputStream for which -g_pollable_output_stream_can_poll() returns %TRUE or else the -behavior is undefined. If @blocking is %TRUE, then @stream does not -need to be a #GPollableOutputStream. - - - the number of bytes written, or -1 on error. - - - - - a #GOutputStream. - - - - the buffer - containing the data to write. - - - - - - the number of bytes to write - - - - whether to do blocking I/O - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Tries to write @count bytes to @stream, as with -g_output_stream_write_all(), but using g_pollable_stream_write() -rather than g_output_stream_write(). - -On a successful write of @count bytes, %TRUE is returned, and -@bytes_written is set to @count. - -If there is an error during the operation (including -%G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is -returned and @error is set to indicate the error status, -@bytes_written is updated to contain the number of bytes written -into the stream before the error occurred. - -As with g_pollable_stream_write(), if @blocking is %FALSE, then -@stream must be a #GPollableOutputStream for which -g_pollable_output_stream_can_poll() returns %TRUE or else the -behavior is undefined. If @blocking is %TRUE, then @stream does not -need to be a #GPollableOutputStream. - - - %TRUE on success, %FALSE if there was an error - - - - - a #GOutputStream. - - - - the buffer - containing the data to write. - - - - - - the number of bytes to write - - - - whether to do blocking I/O - - - - location to store the number of bytes that was - written to the stream - - - - optional #GCancellable object, %NULL to ignore. - - - - - - Find the `gio-proxy` extension point for a proxy implementation that supports -the specified protocol. - - - return a #GProxy or NULL if protocol - is not supported. - - - - - the proxy protocol name (e.g. http, socks, etc) - - - - - - Gets the default #GProxyResolver for the system. - - - the default #GProxyResolver. - - - - - Gets the #GResolver Error Quark. - - a #GQuark. - - - - - Gets the #GResource Error Quark. - - a #GQuark - - - - - Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. - -If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). - -If @filename is empty or the data in it is corrupt, -%G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. - - - a new #GResource, or %NULL on error - - - - - the path of a filename to load, in the GLib filename encoding - - - - - - Returns all the names of children at the specified @path in the set of -globally registered resources. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). - -@lookup_flags controls the behaviour of the lookup. - - - an array of constant strings - - - - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Looks for a file at the specified @path in the set of -globally registered resources and if found returns information about it. - -@lookup_flags controls the behaviour of the lookup. - - - %TRUE if the file was found. %FALSE if there were errors - - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - a location to place the length of the contents of the file, - or %NULL if the length is not needed - - - - a location to place the #GResourceFlags about the file, - or %NULL if the flags are not needed - - - - - - Looks for a file at the specified @path in the set of -globally registered resources and returns a #GBytes that -lets you directly access the data in memory. - -The data is always followed by a zero byte, so you -can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. - -For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section -in the program binary. For compressed files we allocate memory on -the heap and automatically uncompress the data. - -@lookup_flags controls the behaviour of the lookup. - - - #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() - - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Looks for a file at the specified @path in the set of -globally registered resources and returns a #GInputStream -that lets you read the data. - -@lookup_flags controls the behaviour of the lookup. - - - #GInputStream or %NULL on error. - Free the returned object with g_object_unref() - - - - - A pathname inside the resource - - - - A #GResourceLookupFlags - - - - - - Registers the resource with the process-global set of resources. -Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). - - - - - - - A #GResource - - - - - - Unregisters the resource from the process-global set of resources. - - - - - - - A #GResource - - - - - - Gets the default system schema source. - -This function is not required for normal uses of #GSettings but it -may be useful to authors of plugin management systems or to those who -want to introspect the content of schemas. - -If no schemas are installed, %NULL will be returned. - -The returned source may actually consist of multiple schema sources -from different directories, depending on which directories were given -in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all -lookups performed against the default source should probably be done -recursively. - - - the default schema source - - - - - Reports an error in an asynchronous function in an idle function by -directly setting the contents of the #GAsyncResult with the given error -information. - Use g_task_report_error(). - - - - - - - a #GObject, or %NULL. - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - a #GQuark containing the error domain (usually #G_IO_ERROR). - - - - a specific error code. - - - - a formatted error reporting string. - - - - a list of variables to fill in @format. - - - - - - Reports an error in an idle function. Similar to -g_simple_async_report_error_in_idle(), but takes a #GError rather -than building a new one. - Use g_task_report_error(). - - - - - - - a #GObject, or %NULL - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - the #GError to report - - - - - - Reports an error in an idle function. Similar to -g_simple_async_report_gerror_in_idle(), but takes over the caller's -ownership of @error, so the caller does not have to free it any more. - Use g_task_report_error(). - - - - - - - a #GObject, or %NULL - - - - a #GAsyncReadyCallback. - - - - user data passed to @callback. - - - - the #GError to report - - - - - - Sorts @targets in place according to the algorithm in RFC 2782. - - - the head of the sorted list. - - - - - - - a #GList of #GSrvTarget - - - - - - - - Gets the default #GTlsBackend for the system. - - - a #GTlsBackend - - - - - Creates a new #GTlsClientConnection wrapping @base_io_stream (which -must have pollable input and output streams) which is assumed to -communicate with the server identified by @server_identity. - -See the documentation for #GTlsConnection:base-io-stream for restrictions -on when application code can run operations on the @base_io_stream after -this function has returned. - - - the new -#GTlsClientConnection, or %NULL on error - - - - - the #GIOStream to wrap - - - - the expected identity of the server - - - - - - Gets the TLS error quark. - - a #GQuark. - - - - - Creates a new #GTlsFileDatabase which uses anchor certificate authorities -in @anchors to verify certificate chains. - -The certificates in @anchors must be PEM encoded. - - - the new -#GTlsFileDatabase, or %NULL on error - - - - - filename of anchor certificate authorities. - - - - - - Creates a new #GTlsServerConnection wrapping @base_io_stream (which -must have pollable input and output streams). - -See the documentation for #GTlsConnection:base-io-stream for restrictions -on when application code can run operations on the @base_io_stream after -this function has returned. - - - the new -#GTlsServerConnection, or %NULL on error - - - - - the #GIOStream to wrap - - - - the default server certificate, or %NULL - - - - - - Determines if @mount_path is considered an implementation of the -OS. This is primarily used for hiding mountable and mounted volumes -that only are used in the OS and has little to no relevance to the -casual user. - - - %TRUE if @mount_path is considered an implementation detail - of the OS. - - - - - a mount path, e.g. `/media/disk` or `/usr` - - - - - - Determines if @device_path is considered a block device path which is only -used in implementation of the OS. This is primarily used for hiding -mounted volumes that are intended as APIs for programs to read, and system -administrators at a shell; rather than something that should, for example, -appear in a GUI. For example, the Linux `/proc` filesystem. - -The list of device paths considered ‘system’ ones may change over time. - - - %TRUE if @device_path is considered an implementation detail of - the OS. - - - - - a device path, e.g. `/dev/loop0` or `nfsd` - - - - - - Determines if @fs_type is considered a type of file system which is only -used in implementation of the OS. This is primarily used for hiding -mounted volumes that are intended as APIs for programs to read, and system -administrators at a shell; rather than something that should, for example, -appear in a GUI. For example, the Linux `/proc` filesystem. - -The list of file system types considered ‘system’ ones may change over time. - - - %TRUE if @fs_type is considered an implementation detail of the OS. - - - - - a file system type, e.g. `procfs` or `tmpfs` - - - - - - Gets a #GUnixMountEntry for a given mount path. If @time_read -is set, it will be filled with a unix timestamp for checking -if the mounts have changed since with g_unix_mounts_changed_since(). - -If more mounts have the same mount path, the last matching mount -is returned. - - - a #GUnixMountEntry. - - - - - path for a possible unix mount. - - - - guint64 to contain a timestamp. - - - - - - Compares two unix mounts. - - - 1, 0 or -1 if @mount1 is greater than, equal to, -or less than @mount2, respectively. - - - - - first #GUnixMountEntry to compare. - - - - second #GUnixMountEntry to compare. - - - - - - Makes a copy of @mount_entry. - - - a new #GUnixMountEntry - - - - - a #GUnixMountEntry. - - - - - - Gets a #GUnixMountEntry for a given file path. If @time_read -is set, it will be filled with a unix timestamp for checking -if the mounts have changed since with g_unix_mounts_changed_since(). - -If more mounts have the same mount path, the last matching mount -is returned. - - - a #GUnixMountEntry. - - - - - file path on some unix mount. - - - - guint64 to contain a timestamp. - - - - - - Frees a unix mount. - - - - - - - a #GUnixMountEntry. - - - - - - Gets the device path for a unix mount. - - - a string containing the device path. - - - - - a #GUnixMount. - - - - - - Gets the filesystem type for the unix mount. - - - a string containing the file system type. - - - - - a #GUnixMount. - - - - - - Gets the mount path for a unix mount. - - - the mount path for @mount_entry. - - - - - input #GUnixMountEntry to get the mount path for. - - - - - - Gets a comma-separated list of mount options for the unix mount. For example, -`rw,relatime,seclabel,data=ordered`. - -This is similar to g_unix_mount_point_get_options(), but it takes -a #GUnixMountEntry as an argument. - - - a string containing the options, or %NULL if not -available. - - - - - a #GUnixMountEntry. - - - - - - Gets the root of the mount within the filesystem. This is useful e.g. for -mounts created by bind operation, or btrfs subvolumes. - -For example, the root path is equal to "/" for mount created by -"mount /dev/sda1 /mnt/foo" and "/bar" for -"mount --bind /mnt/foo/bar /mnt/bar". - - - a string containing the root, or %NULL if not supported. - - - - - a #GUnixMountEntry. - - - - - - Guesses whether a Unix mount can be ejected. - - - %TRUE if @mount_entry is deemed to be ejectable. - - - - - a #GUnixMountEntry - - - - - - Guesses the icon of a Unix mount. - - - a #GIcon - - - - - a #GUnixMountEntry - - - - - - Guesses the name of a Unix mount. -The result is a translated string. - - - A newly allocated string that must - be freed with g_free() - - - - - a #GUnixMountEntry - - - - - - Guesses whether a Unix mount should be displayed in the UI. - - - %TRUE if @mount_entry is deemed to be displayable. - - - - - a #GUnixMountEntry - - - - - - Guesses the symbolic icon of a Unix mount. - - - a #GIcon - - - - - a #GUnixMountEntry - - - - - - Checks if a unix mount is mounted read only. - - - %TRUE if @mount_entry is read only. - - - - - a #GUnixMount. - - - - - - Checks if a Unix mount is a system mount. This is the Boolean OR of -g_unix_is_system_fs_type(), g_unix_is_system_device_path() and -g_unix_is_mount_path_system_internal() on @mount_entry’s properties. - -The definition of what a ‘system’ mount entry is may change over time as new -file system types and device paths are ignored. - - - %TRUE if the unix mount is for a system path. - - - - - a #GUnixMount. - - - - - - Checks if the unix mount points have changed since a given unix time. - - - %TRUE if the mount points have changed since @time. - - - - - guint64 to contain a timestamp. - - - - - - Gets a #GList of #GUnixMountPoint containing the unix mount points. -If @time_read is set, it will be filled with the mount timestamp, -allowing for checking if the mounts have changed with -g_unix_mount_points_changed_since(). - - - - a #GList of the UNIX mountpoints. - - - - - - - guint64 to contain a timestamp. - - - - - - Checks if the unix mounts have changed since a given unix time. - - - %TRUE if the mounts have changed since @time. - - - - - guint64 to contain a timestamp. - - - - - - Gets a #GList of #GUnixMountEntry containing the unix mounts. -If @time_read is set, it will be filled with the mount -timestamp, allowing for checking if the mounts have changed -with g_unix_mounts_changed_since(). - - - - a #GList of the UNIX mounts. - - - - - - - guint64 to contain a timestamp, or %NULL - - - - - - diff --git a/gir-files/Gst-1.0.gir b/gir-files/Gst-1.0.gir deleted file mode 100644 index 91f3a42d4..000000000 --- a/gir-files/Gst-1.0.gir +++ /dev/null @@ -1,52746 +0,0 @@ - - - - - - - - - - - A datatype to hold the handle to an outstanding sync or async clock callback. - - - - - A datatype to hold a time, measured in nanoseconds. - - - - - A datatype to hold a time difference, measured in nanoseconds. - - - - - A type defining the type of an element factory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The allocator name for the default system memory allocator - - - - - Parameters to control the allocation of memory - - - flags to control allocation - - - - the desired alignment of the memory - - - - the desired prefix - - - - the desired padding - - - - - - - - - Create a copy of @params. - -Free-function: gst_allocation_params_free - - - a new ##GstAllocationParams, free with -gst_allocation_params_free(). - - - - - a #GstAllocationParams - - - - - - Free @params - - - - - - - a #GstAllocationParams - - - - - - Initialize @params to its default values - - - - - - - a #GstAllocationParams - - - - - - - Memory is usually created by allocators with a gst_allocator_alloc() -method call. When %NULL is used as the allocator, the default allocator will -be used. - -New allocators can be registered with gst_allocator_register(). -Allocators are identified by name and can be retrieved with -gst_allocator_find(). gst_allocator_set_default() can be used to change the -default allocator. - -New memory can be created with gst_memory_new_wrapped() that wraps the memory -allocated elsewhere. - - - Find a previously registered allocator with @name. When @name is %NULL, the -default allocator will be returned. - - - a #GstAllocator or %NULL when -the allocator with @name was not registered. Use gst_object_unref() -to release the allocator after usage. - - - - - the name of the allocator - - - - - - Registers the memory @allocator with @name. This function takes ownership of -@allocator. - - - - - - - the name of the allocator - - - - #GstAllocator - - - - - - Use @allocator to allocate a new memory block with memory that is at least -@size big. - -The optional @params can specify the prefix and padding for the memory. If -%NULL is passed, no flags, no extra prefix/padding and a default alignment is -used. - -The prefix/padding will be filled with 0 if flags contains -#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. - -When @allocator is %NULL, the default allocator will be used. - -The alignment in @params is given as a bitmask so that @align + 1 equals -the amount of bytes to align to. For example, to align to 8 bytes, -use an alignment of 7. - - - a new #GstMemory. - - - - - a #GstAllocator to use - - - - size of the visible memory area - - - - optional parameters - - - - - - Free @memory that was previously allocated with gst_allocator_alloc(). - - - - - - - a #GstAllocator to use - - - - the memory to free - - - - - - Use @allocator to allocate a new memory block with memory that is at least -@size big. - -The optional @params can specify the prefix and padding for the memory. If -%NULL is passed, no flags, no extra prefix/padding and a default alignment is -used. - -The prefix/padding will be filled with 0 if flags contains -#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. - -When @allocator is %NULL, the default allocator will be used. - -The alignment in @params is given as a bitmask so that @align + 1 equals -the amount of bytes to align to. For example, to align to 8 bytes, -use an alignment of 7. - - - a new #GstMemory. - - - - - a #GstAllocator to use - - - - size of the visible memory area - - - - optional parameters - - - - - - Free @memory that was previously allocated with gst_allocator_alloc(). - - - - - - - a #GstAllocator to use - - - - the memory to free - - - - - - Set the default allocator. This function takes ownership of @allocator. - - - - - - - a #GstAllocator - - - - - - - - - - - - the implementation of the GstMemoryMapFunction - - - - the implementation of the GstMemoryUnmapFunction - - - - the implementation of the GstMemoryCopyFunction - - - - the implementation of the GstMemoryShareFunction - - - - the implementation of the GstMemoryIsSpanFunction - - - - the implementation of the GstMemoryMapFullFunction. - Will be used instead of @mem_map if present. (Since: 1.6) - - - - the implementation of the GstMemoryUnmapFullFunction. - Will be used instead of @mem_unmap if present. (Since: 1.6) - - - - - - - - - - - - - The #GstAllocator is used to create new memory. - - - Object parent class - - - - - - - a new #GstMemory. - - - - - a #GstAllocator to use - - - - size of the visible memory area - - - - optional parameters - - - - - - - - - - - - - - a #GstAllocator to use - - - - the memory to free - - - - - - - - - - - - - Flags for allocators. - - The allocator has a custom alloc function. - - - first flag that can be used for custom purposes - - - - - - - The #GstAtomicQueue object implements a queue that can be used from multiple -threads without performing any blocking operations. - - - Create a new atomic queue instance. @initial_size will be rounded up to the -nearest power of 2 and used as the initial size of the queue. - - - a new #GstAtomicQueue - - - - - initial queue size - - - - - - Get the amount of items in the queue. - - - the number of elements in the queue. - - - - - a #GstAtomicQueue - - - - - - Peek the head element of the queue without removing it from the queue. - - - the head element of @queue or -%NULL when the queue is empty. - - - - - a #GstAtomicQueue - - - - - - Get the head element of the queue. - - - the head element of @queue or %NULL when -the queue is empty. - - - - - a #GstAtomicQueue - - - - - - Append @data to the tail of the queue. - - - - - - - a #GstAtomicQueue - - - - the data - - - - - - Increase the refcount of @queue. - - - - - - - a #GstAtomicQueue - - - - - - Unref @queue and free the memory when the refcount reaches 0. - - - - - - - a #GstAtomicQueue - - - - - - - - - - - - - - - - - - - - - Gets the list with children in a bin. - - - - a #GstBin - - - - - Gets the children cookie that watches the children list. - - - - a #GstBin - - - - - - - - - - - - - - - - - - - Check if @bin will resync its state change when elements are added and -removed. - - - - A #GstBin - - - - - Gets the number of children in a bin. - - - - a #GstBin - - - - - - - - - - - - - - - - - - - Combination of all possible fields that can be copied with -gst_buffer_copy_into(). - - - - - Combination of all possible metadata fields that can be copied with -gst_buffer_copy_into(). - - - - - The decoding timestamp (dts) in nanoseconds (as a #GstClockTime) -of the data in the buffer. This is the timestamp when the media should be -decoded or processed otherwise. -Value will be %GST_CLOCK_TIME_NONE if the dts is unknown. - - - - a #GstBuffer.: - - - - - Tests if the dts is known. - - - - a #GstBuffer - - - - - Returns the buffer decoding timestamp (dts) if valid, else the buffer -presentation time (pts) - - - - a #GstBuffer.: - - - - - The duration in nanoseconds (as a #GstClockTime) of the data in the buffer. -Value will be %GST_CLOCK_TIME_NONE if the duration is unknown. - - - - a #GstBuffer. - - - - - Tests if the duration is known. - - - - a #GstBuffer - - - - - A flags word containing #GstBufferFlags flags set on this buffer. - - - - a #GstBuffer. - - - - - Gives the status of a specific flag on a buffer. - - - - a #GstBuffer. - - - the #GstBufferFlags flag to check. - - - - - Sets a buffer flag on a buffer. - - - - a #GstBuffer. - - - the #GstBufferFlags flag to set. - - - - - Clears a buffer flag. - - - - a #GstBuffer. - - - the #GstBufferFlags flag to clear. - - - - - Tests if the buffer marks a discontinuity in the stream. - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - The offset in the source file of the beginning of this buffer. - - - - a #GstBuffer. - - - - - The offset in the source file of the end of this buffer. - - - - a #GstBuffer. - - - - - Tests if the end offset is known. - - - - a #GstBuffer - - - - - Tests if the start offset is known. - - - - a #GstBuffer - - - - - Constant for no-offset return results. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Check if the bufferpool is flushing. Subclasses might want to check the -state of the pool in the acquire function. - - - - a GstBufferPool - - - - - The presentation timestamp (pts) in nanoseconds (as a #GstClockTime) -of the data in the buffer. This is the timestamp when the media should be -presented to the user. -Value will be %GST_CLOCK_TIME_NONE if the pts is unknown. - - - - a #GstBuffer.: - - - - - Tests if the pts is known. - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstBin is an element that can contain other #GstElement, allowing them to be -managed as a group. -Pads from the child elements can be ghosted to the bin, see #GstGhostPad. -This makes the bin look like any other elements and enables creation of -higher-level abstraction elements. - -A new #GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you -want to create a toplevel bin because a normal bin doesn't have a bus or -handle clock distribution of its own. - -After the bin has been created you will typically add elements to it with -gst_bin_add(). You can remove elements with gst_bin_remove(). - -An element can be retrieved from a bin with gst_bin_get_by_name(), using the -elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal -purposes and will query the parent bins when the element is not found in the -current bin. - -An iterator of elements in a bin can be retrieved with -gst_bin_iterate_elements(). Various other iterators exist to retrieve the -elements in a bin. - -gst_object_unref() is used to drop your reference to the bin. - -The #GstBin::element-added signal is fired whenever a new element is added to -the bin. Likewise the #GstBin::element-removed signal is fired whenever an -element is removed from the bin. - -## Notes - -A #GstBin internally intercepts every #GstMessage posted by its children and -implements the following default behaviour for each of them: - -* GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING -state. If all sinks posted the EOS message, this bin will post and EOS -message upwards. - -* GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. -The messages are used to decide when all elements have completed playback -of their segment. - -* GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted -a SEGMENT_START have posted a SEGMENT_DONE. - -* GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change -in the stream duration. The duration change is posted to the -application so that it can refetch the new duration with a duration -query. Note that these messages can be posted before the bin is -prerolled, in which case the duration query might fail. Note also that -there might be a discrepancy (due to internal buffering/queueing) between the -stream being currently displayed and the returned duration query. -Applications might want to also query for duration (and changes) by -listening to the GST_MESSAGE_STREAM_START message, signaling the active start -of a (new) stream. - -* GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it -can no longer provide a clock. The default bin behaviour is to -check if the lost clock was the one provided by the bin. If so and -the bin is currently in the PLAYING state, the message is forwarded to -the bin parent. -This message is also generated when a clock provider is removed from -the bin. If this message is received by the application, it should -PAUSE the pipeline and set it back to PLAYING to force a new clock -distribution. - -* GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element -can provide a clock. This mostly happens when a new clock -provider is added to the bin. The default behaviour of the bin is to -mark the currently selected clock as dirty, which will perform a clock -recalculation the next time the bin is asked to provide a clock. -This message is never sent tot the application but is forwarded to -the parent of the bin. - -* OTHERS: posted upwards. - -A #GstBin implements the following default behaviour for answering to a -#GstQuery: - -* GST_QUERY_DURATION: The bin will forward the query to all sink -elements contained within and will return the maximum value. -If no sinks are available in the bin, the query fails. - -* GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the -MAXIMUM of all values is returned. If no sinks are available in the bin, -the query fails. - -* OTHERS:the query is forwarded to all sink elements, the result -of the first sink that answers the query successfully is returned. If no -sink is in the bin, the query fails. - -A #GstBin will by default forward any event sent to it to all sink -(#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements -depending on the event type. -If all the elements return %TRUE, the bin will also return %TRUE, else %FALSE -is returned. If no elements of the required type are in the bin, the event -handler will return %TRUE. - - - - Creates a new bin with the given name. - - - a new #GstBin - - - - - the name of the new bin - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Adds the given element to the bin. Sets the element's parent, and thus -takes ownership of the element. An element can only be added to one bin. - -If the element's pads are linked to other pads, the pads will be unlinked -before the element is added to the bin. - -> When you add an element to an already-running pipeline, you will have to -> take care to set the state of the newly-added element to the desired -> state (usually PLAYING or PAUSED, same you set the pipeline to originally) -> with gst_element_set_state(), or use gst_element_sync_state_with_parent(). -> The bin or pipeline will not take care of this for you. - -MT safe. - - - %TRUE if the element could be added, %FALSE if -the bin does not want to accept the element. - - - - - a #GstBin - - - - the #GstElement to add - - - - - - Adds a %NULL-terminated list of elements to a bin. This function is -equivalent to calling gst_bin_add() for each member of the list. The return -value of each gst_bin_add() is ignored. - - - - - - - a #GstBin - - - - the #GstElement element to add to the bin - - - - additional elements to add to the bin - - - - - - Recursively looks for elements with an unlinked pad of the given -direction within the specified bin and returns an unlinked pad -if one is found, or %NULL otherwise. If a pad is found, the caller -owns a reference to it and should use gst_object_unref() on the -pad when it is not needed any longer. - - - unlinked pad of the given -direction, %NULL. - - - - - bin in which to look for elements with unlinked pads - - - - whether to look for an unlinked source or sink pad - - - - - - Looks for an element inside the bin that implements the given -interface. If such an element is found, it returns the element. -You can cast this element to the given interface afterwards. If you want -all elements that implement the interface, use -gst_bin_iterate_all_by_interface(). This function recurses into child bins. - -MT safe. Caller owns returned reference. - - - A #GstElement inside the bin -implementing the interface - - - - - a #GstBin - - - - the #GType of an interface - - - - - - Gets the element with the given name from a bin. This -function recurses into child bins. - -Returns %NULL if no element with the given name is found in the bin. - -MT safe. Caller owns returned reference. - - - the #GstElement with the given -name, or %NULL - - - - - a #GstBin - - - - the element name to search for - - - - - - Gets the element with the given name from this bin. If the -element is not found, a recursion is performed on the parent bin. - -Returns %NULL if: -- no element with the given name is found in the bin - -MT safe. Caller owns returned reference. - - - the #GstElement with the given -name, or %NULL - - - - - a #GstBin - - - - the element name to search for - - - - - - Return the suppressed flags of the bin. - -MT safe. - - - the bin's suppressed #GstElementFlags. - - - - - a #GstBin - - - - - - Looks for all elements inside the bin with the given element factory name. -The function recurses inside child bins. The iterator will yield a series of -#GstElement that should be unreffed after use. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement - for all elements in the bin with the given element factory name, - or %NULL. - - - - - a #GstBin - - - - the name of the #GstElementFactory - - - - - - Looks for all elements inside the bin that implements the given -interface. You can safely cast all returned elements to the given interface. -The function recurses inside child bins. The iterator will yield a series -of #GstElement that should be unreffed after use. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement - for all elements in the bin implementing the given interface, - or %NULL - - - - - a #GstBin - - - - the #GType of an interface - - - - - - Gets an iterator for the elements in this bin. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement, -or %NULL - - - - - a #GstBin - - - - - - Gets an iterator for the elements in this bin. -This iterator recurses into GstBin children. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement, -or %NULL - - - - - a #GstBin - - - - - - Gets an iterator for all elements in the bin that have the -#GST_ELEMENT_FLAG_SINK flag set. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement, -or %NULL - - - - - a #GstBin - - - - - - Gets an iterator for the elements in this bin in topologically -sorted order. This means that the elements are returned from -the most downstream elements (sinks) to the sources. - -This function is used internally to perform the state changes -of the bin elements and for clock selection. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement, -or %NULL - - - - - a #GstBin - - - - - - Gets an iterator for all elements in the bin that have the -#GST_ELEMENT_FLAG_SOURCE flag set. - -MT safe. Caller owns returned value. - - - a #GstIterator of #GstElement, -or %NULL - - - - - a #GstBin - - - - - - Query @bin for the current latency using and reconfigures this latency to all the -elements with a LATENCY event. - -This method is typically called on the pipeline when a #GST_MESSAGE_LATENCY -is posted on the bus. - -This function simply emits the 'do-latency' signal so any custom latency -calculations will be performed. - - - %TRUE if the latency could be queried and reconfigured. - - - - - a #GstBin - - - - - - Removes the element from the bin, unparenting it as well. -Unparenting the element means that the element will be dereferenced, -so if the bin holds the only reference to the element, the element -will be freed in the process of removing it from the bin. If you -want the element to still exist after removing, you need to call -gst_object_ref() before removing it from the bin. - -If the element's pads are linked to other pads, the pads will be unlinked -before the element is removed from the bin. - -MT safe. - - - %TRUE if the element could be removed, %FALSE if -the bin does not want to remove the element. - - - - - a #GstBin - - - - the #GstElement to remove - - - - - - Remove a list of elements from a bin. This function is equivalent -to calling gst_bin_remove() with each member of the list. - - - - - - - a #GstBin - - - - the first #GstElement to remove from the bin - - - - %NULL-terminated list of elements to remove from the bin - - - - - - Suppress the given flags on the bin. #GstElementFlags of a -child element are propagated when it is added to the bin. -When suppressed flags are set, those specified flags will -not be propagated to the bin. - -MT safe. - - - - - - - a #GstBin - - - - the #GstElementFlags to suppress - - - - - - Synchronizes the state of every child of @bin with the state -of @bin. See also gst_element_sync_state_with_parent(). - - - %TRUE if syncing the state was successful for all children, - otherwise %FALSE. - - - - - a #GstBin - - - - - - If set to %TRUE, the bin will handle asynchronous state changes. -This should be used only if the bin subclass is modifying the state -of its children on its own. - - - - Forward all children messages, even those that would normally be filtered by -the bin. This can be interesting when one wants to be notified of the EOS -state of individual elements, for example. - -The messages are converted to an ELEMENT message with the bin as the -source. The structure of the message is named 'GstBinForwarded' and contains -a field named 'message' of type GST_TYPE_MESSAGE that contains the original -forwarded message. - - - - - - - the number of children in this bin - - - - the list of children in this bin - - - - - - updated whenever @children changes - - - - internal bus for handling child messages - - - - queued and cached messages - - - - - - the bin is currently calculating its state - - - - the bin needs to recalculate its state (deprecated) - - - - the bin needs to select a new clock - - - - the last clock selected - - - - the element that provided @provided_clock - - - - - - - - - - - - Will be emitted after the element was added to sub_bin. - - - - - - the #GstBin the element was added to - - - - the #GstElement that was added to @sub_bin - - - - - - Will be emitted after the element was removed from sub_bin. - - - - - - the #GstBin the element was removed from - - - - the #GstElement that was removed from @sub_bin - - - - - - Will be emitted when the bin needs to perform latency calculations. This -signal is only emitted for toplevel bins or when async-handling is -enabled. - -Only one signal handler is invoked. If no signals are connected, the -default handler is invoked, which will query and distribute the lowest -possible latency to all sinks. - -Connect to this signal if the default latency calculations are not -sufficient, like when you need different latencies for different sinks in -the same pipeline. - - - - - - Will be emitted after the element was added to the bin. - - - - - - the #GstElement that was added to the bin - - - - - - Will be emitted after the element was removed from the bin. - - - - - - the #GstElement that was removed from the bin - - - - - - - Subclasses can override the @add_element and @remove_element to -update the list of children in the bin. - -The @handle_message method can be overridden to implement custom -message handling. @handle_message takes ownership of the message, just like -#gst_element_post_message. - -The @deep_element_added vfunc will be called when a new element has been -added to any bin inside this bin, so it will also be called if a new child -was added to a sub-bin of this bin. #GstBin implementations that override -this message should chain up to the parent class implementation so the -#GstBin::deep-element-added signal is emitted on all parents. - - - bin parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GstBinFlags are a set of flags specific to bins. Most are set/used -internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro, -and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET (). - - don't resync a state change when elements are - added or linked in the bin (Since: 1.0.5) - - - Indicates whether the bin can handle elements - that add/remove source pads at any point in time without - first posting a no-more-pads signal (Since: 1.10) - - - the last enum in the series of flags for bins. -Derived classes can use this as first value in a list of flags. - - - - - - - A fundamental type that describes a 64-bit bitmask - - - Buffers are the basic unit of data transfer in GStreamer. They contain the -timing and offset along with other arbitrary metadata that is associated -with the #GstMemory blocks that the buffer contains. - -Buffers are usually created with gst_buffer_new(). After a buffer has been -created one will typically allocate memory for it and add it to the buffer. -The following example creates a buffer that can hold a given video frame -with a given width, height and bits per plane. -|[<!-- language="C" --> - GstBuffer *buffer; - GstMemory *memory; - gint size, width, height, bpp; - ... - size = width * height * bpp; - buffer = gst_buffer_new (); - memory = gst_allocator_alloc (NULL, size, NULL); - gst_buffer_insert_memory (buffer, -1, memory); - ... -]| - -Alternatively, use gst_buffer_new_allocate() to create a buffer with -preallocated data of a given size. - -Buffers can contain a list of #GstMemory objects. You can retrieve how many -memory objects with gst_buffer_n_memory() and you can get a pointer -to memory with gst_buffer_peek_memory() - -A buffer will usually have timestamps, and a duration, but neither of these -are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a -meaningful value can be given for these, they should be set. The timestamps -and duration are measured in nanoseconds (they are #GstClockTime values). - -The buffer DTS refers to the timestamp when the buffer should be decoded and -is usually monotonically increasing. The buffer PTS refers to the timestamp when -the buffer content should be presented to the user and is not always -monotonically increasing. - -A buffer can also have one or both of a start and an end offset. These are -media-type specific. For video buffers, the start offset will generally be -the frame number. For audio buffers, it will be the number of samples -produced so far. For compressed data, it could be the byte offset in a -source or destination file. Likewise, the end offset will be the offset of -the end of the buffer. These can only be meaningfully interpreted if you -know the media type of the buffer (the preceding CAPS event). Either or both -can be set to #GST_BUFFER_OFFSET_NONE. - -gst_buffer_ref() is used to increase the refcount of a buffer. This must be -done when you want to keep a handle to the buffer after pushing it to the -next element. The buffer refcount determines the writability of the buffer, a -buffer is only writable when the refcount is exactly 1, i.e. when the caller -has the only reference to the buffer. - -To efficiently create a smaller buffer out of an existing one, you can -use gst_buffer_copy_region(). This method tries to share the memory objects -between the two buffers. - -If a plug-in wants to modify the buffer data or metadata in-place, it should -first obtain a buffer that is safe to modify by using -gst_buffer_make_writable(). This function is optimized so that a copy will -only be made when it is necessary. - -Several flags of the buffer can be set and unset with the -GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use -GST_BUFFER_FLAG_IS_SET() to test if a certain #GstBufferFlags flag is set. - -Buffers can be efficiently merged into a larger buffer with -gst_buffer_append(). Copying of memory will only be done when absolutely -needed. - -Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta(). -Metadata can be retrieved with gst_buffer_get_meta(). See also #GstMeta - -An element should either unref the buffer or push it out on a src pad -using gst_pad_push() (see #GstPad). - -Buffers are usually freed by unreffing them with gst_buffer_unref(). When -the refcount drops to 0, any memory and metadata pointed to by the buffer is -unreffed as well. Buffers allocated from a #GstBufferPool will be returned to -the pool when the refcount drops to 0. - -The #GstParentBufferMeta is a meta which can be attached to a #GstBuffer -to hold a reference to another buffer that is only released when the child -#GstBuffer is released. - -Typically, #GstParentBufferMeta is used when the child buffer is directly -using the #GstMemory of the parent buffer, and wants to prevent the parent -buffer from being returned to a buffer pool until the #GstMemory is available -for re-use. (Since: 1.6) - - - the parent structure - - - - pointer to the pool owner of the buffer - - - - presentation timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the - pts is not known or relevant. The pts contains the timestamp when the - media should be presented to the user. - - - - decoding timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the - dts is not known or relevant. The dts contains the timestamp when the - media should be processed. - - - - duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE - when the duration is not known or relevant. - - - - a media specific offset for the buffer data. - For video frames, this is the frame number of this buffer. - For audio samples, this is the offset of the first sample in this buffer. - For file data or compressed data this is the byte offset of the first - byte in this buffer. - - - - the last offset contained in this buffer. It has the same - format as @offset. - - - - Creates a newly allocated buffer without any data. - -MT safe. - - - the new #GstBuffer. - - - - - Tries to create a newly allocated buffer with data of the given size and -extra parameters from @allocator. If the requested amount of memory can't be -allocated, %NULL will be returned. The allocated buffer memory is not cleared. - -When @allocator is %NULL, the default memory allocator will be used. - -Note that when @size == 0, the buffer will not have memory associated with it. - -MT safe. - - - a new #GstBuffer, or %NULL if - the memory couldn't be allocated. - - - - - the #GstAllocator to use, or %NULL to use the - default allocator - - - - the size in bytes of the new buffer's data. - - - - optional parameters - - - - - - Creates a new buffer that wraps the given @data. The memory will be freed -with g_free and will be marked writable. - -MT safe. - - - a new #GstBuffer - - - - - data to wrap - - - - - - allocated size of @data - - - - - - Creates a new #GstBuffer that wraps the given @bytes. The data inside -@bytes cannot be %NULL and the resulting buffer will be marked as read only. - -MT safe. - - - a new #GstBuffer wrapping @bytes - - - - - a #GBytes to wrap - - - - - - Allocate a new buffer that wraps the given memory. @data must point to -@maxsize of memory, the wrapped buffer will have the region from @offset and -@size visible. - -When the buffer is destroyed, @notify will be called with @user_data. - -The prefix/padding must be filled with 0 if @flags contains -#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. - - - a new #GstBuffer - - - - - #GstMemoryFlags - - - - data to wrap - - - - - - allocated size of @data - - - - offset in @data - - - - size of valid data - - - - user_data - - - - called with @user_data when the memory is freed - - - - - - Add metadata for @info to @buffer using the parameters in @params. - - - the metadata for the api in @info on @buffer. - - - - - a #GstBuffer - - - - a #GstMetaInfo - - - - params for @info - - - - - - Add a #GstParentBufferMeta to @buffer that holds a reference on -@ref until the buffer is freed. - - - The #GstParentBufferMeta that was added to the buffer - - - - - a #GstBuffer - - - - a #GstBuffer to ref - - - - - - Attaches protection metadata to a #GstBuffer. - - - a pointer to the added #GstProtectionMeta if successful; %NULL if -unsuccessful. - - - - - #GstBuffer holding an encrypted sample, to which protection - metadata should be added. - - - - a #GstStructure holding cryptographic - information relating to the sample contained in @buffer. This - function takes ownership of @info. - - - - - - Add a #GstReferenceTimestampMeta to @buffer that holds a @timestamp and -optionally @duration based on a specific timestamp @reference. See the -documentation of #GstReferenceTimestampMeta for details. - - - The #GstReferenceTimestampMeta that was added to the buffer - - - - - a #GstBuffer - - - - identifier for the timestamp reference. - - - - timestamp - - - - duration, or %GST_CLOCK_TIME_NONE - - - - - - Append all the memory from @buf2 to @buf1. The result buffer will contain a -concatenation of the memory of @buf1 and @buf2. - - - the new #GstBuffer that contains the memory - of the two source buffers. - - - - - the first source #GstBuffer to append. - - - - the second source #GstBuffer to append. - - - - - - Append the memory block @mem to @buffer. This function takes -ownership of @mem and thus doesn't increase its refcount. - -This function is identical to gst_buffer_insert_memory() with an index of -1. -See gst_buffer_insert_memory() for more details. - - - - - - - a #GstBuffer. - - - - a #GstMemory. - - - - - - Append @size bytes at @offset from @buf2 to @buf1. The result buffer will -contain a concatenation of the memory of @buf1 and the requested region of -@buf2. - - - the new #GstBuffer that contains the memory - of the two source buffers. - - - - - the first source #GstBuffer to append. - - - - the second source #GstBuffer to append. - - - - the offset in @buf2 - - - - the size or -1 of @buf2 - - - - - - Create a copy of the given buffer. This will only copy the buffer's -data to a newly allocated memory if needed (if the type of memory -requires it), otherwise the underlying data is just referenced. -Check gst_buffer_copy_deep() if you want to force the data -to be copied to newly allocated memory. - - - a new copy of @buf. - - - - - a #GstBuffer. - - - - - - Create a copy of the given buffer. This will make a newly allocated -copy of the data the source buffer contains. - - - a new copy of @buf. - - - - - a #GstBuffer. - - - - - - Copies the information from @src into @dest. - -If @dest already contains memory and @flags contains GST_BUFFER_COPY_MEMORY, -the memory from @src will be appended to @dest. - -@flags indicate which fields will be copied. - - - %TRUE if the copying succeeded, %FALSE otherwise. - - - - - a destination #GstBuffer - - - - a source #GstBuffer - - - - flags indicating what metadata fields should be copied. - - - - offset to copy from - - - - total size to copy. If -1, all data is copied. - - - - - - Creates a sub-buffer from @parent at @offset and @size. -This sub-buffer uses the actual memory space of the parent buffer. -This function will copy the offset and timestamp fields when the -offset is 0. If not, they will be set to #GST_CLOCK_TIME_NONE and -#GST_BUFFER_OFFSET_NONE. -If @offset equals 0 and @size equals the total size of @buffer, the -duration and offset end fields are also copied. If not they will be set -to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. - -MT safe. - - - the new #GstBuffer or %NULL if the arguments were - invalid. - - - - - a #GstBuffer. - - - - the #GstBufferCopyFlags - - - - the offset into parent #GstBuffer at which the new sub-buffer - begins. - - - - the size of the new #GstBuffer sub-buffer, in bytes. If -1, all - data is copied. - - - - - - Copy @size bytes starting from @offset in @buffer to @dest. - - - The amount of bytes extracted. This value can be lower than @size - when @buffer did not contain enough data. - - - - - a #GstBuffer. - - - - the offset to extract - - - - - the destination address - - - - - - the size to extract - - - - - - Extracts a copy of at most @size bytes the data at @offset into -newly-allocated memory. @dest must be freed using g_free() when done. - - - - - - - a #GstBuffer - - - - the offset to extract - - - - the size to extract - - - - A pointer where - the destination array will be written. Might be %NULL if the size is 0. - - - - - - A location where the size of @dest can be written - - - - - - Copy @size bytes from @src to @buffer at @offset. - - - The amount of bytes copied. This value can be lower than @size - when @buffer did not contain enough data. - - - - - a #GstBuffer. - - - - the offset to fill - - - - the source address - - - - - - the size to fill - - - - - - Find the memory blocks that span @size bytes starting from @offset -in @buffer. - -When this function returns %TRUE, @idx will contain the index of the first -memory block where the byte for @offset can be found and @length contains the -number of memory blocks containing the @size remaining bytes. @skip contains -the number of bytes to skip in the memory block at @idx to get to the byte -for @offset. - -@size can be -1 to get all the memory blocks after @idx. - - - %TRUE when @size bytes starting from @offset could be found in -@buffer and @idx, @length and @skip will be filled. - - - - - a #GstBuffer. - - - - an offset - - - - a size - - - - pointer to index - - - - pointer to length - - - - pointer to skip - - - - - - Call @func with @user_data for each meta in @buffer. - -@func can modify the passed meta pointer or its contents. The return value -of @func define if this function returns or if the remaining metadata items -in the buffer should be skipped. - - - %FALSE when @func returned %FALSE for one of the metadata. - - - - - a #GstBuffer - - - - a #GstBufferForeachMetaFunc to call - - - - user data passed to @func - - - - - - Get all the memory block in @buffer. The memory blocks will be merged -into one large #GstMemory. - - - a #GstMemory that contains the merged memory. -Use gst_memory_unref () after usage. - - - - - a #GstBuffer. - - - - - - Get the #GstBufferFlags flags set on this buffer. - - - the flags set on this buffer. - - - - - a #GstBuffer - - - - - - Get the memory block at index @idx in @buffer. - - - a #GstMemory that contains the data of the -memory block at @idx. Use gst_memory_unref () after usage. - - - - - a #GstBuffer. - - - - an index - - - - - - Get @length memory blocks in @buffer starting at @idx. The memory blocks will -be merged into one large #GstMemory. - -If @length is -1, all memory starting from @idx is merged. - - - a #GstMemory that contains the merged data of @length - blocks starting at @idx. Use gst_memory_unref () after usage. - - - - - a #GstBuffer. - - - - an index - - - - a length - - - - - - Get the metadata for @api on buffer. When there is no such metadata, %NULL is -returned. If multiple metadata with the given @api are attached to this -buffer only the first one is returned. To handle multiple metadata with a -given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead -and check the meta->info.api member for the API type. - - - the metadata for @api on -@buffer. - - - - - a #GstBuffer - - - - the #GType of an API - - - - - - - - number of metas of type @api_type on @buffer. - - - - - a #GstBuffer - - - - the #GType of an API - - - - - - Find the first #GstReferenceTimestampMeta on @buffer that conforms to -@reference. Conformance is tested by checking if the meta's reference is a -subset of @reference. - -Buffers can contain multiple #GstReferenceTimestampMeta metadata items. - - - the #GstReferenceTimestampMeta or %NULL when there -is no such metadata on @buffer. - - - - - a #GstBuffer - - - - a reference #GstCaps - - - - - - Get the total size of the memory blocks in @buffer. - - - total size of the memory blocks in @buffer. - - - - - a #GstBuffer. - - - - - - Get the total size of the memory blocks in @b. - -When not %NULL, @offset will contain the offset of the data in the -first memory block in @buffer and @maxsize will contain the sum of -the size and @offset and the amount of extra padding on the last -memory block. @offset and @maxsize can be used to resize the -buffer memory blocks with gst_buffer_resize(). - - - total size of the memory blocks in @buffer. - - - - - a #GstBuffer. - - - - a pointer to the offset - - - - a pointer to the maxsize - - - - - - Get the total size of @length memory blocks stating from @idx in @buffer. - -When not %NULL, @offset will contain the offset of the data in the -memory block in @buffer at @idx and @maxsize will contain the sum of the size -and @offset and the amount of extra padding on the memory block at @idx + -@length -1. -@offset and @maxsize can be used to resize the buffer memory blocks with -gst_buffer_resize_range(). - - - total size of @length memory blocks starting at @idx in @buffer. - - - - - a #GstBuffer. - - - - an index - - - - a length - - - - a pointer to the offset - - - - a pointer to the maxsize - - - - - - Gives the status of a specific flag on a buffer. - - - %TRUE if all flags in @flags are found on @buffer. - - - - - a #GstBuffer - - - - the #GstBufferFlags flag to check. - - - - - - Insert the memory block @mem to @buffer at @idx. This function takes ownership -of @mem and thus doesn't increase its refcount. - -Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is -added, existing memory blocks will automatically be merged to make room for -the new memory. - - - - - - - a #GstBuffer. - - - - the index to add the memory at, or -1 to append it to the end - - - - a #GstMemory. - - - - - - Check if all memory blocks in @buffer are writable. - -Note that this function does not check if @buffer is writable, use -gst_buffer_is_writable() to check that if needed. - - - %TRUE if all memory blocks in @buffer are writable - - - - - a #GstBuffer. - - - - - - Check if @length memory blocks in @buffer starting from @idx are writable. - -@length can be -1 to check all the memory blocks after @idx. - -Note that this function does not check if @buffer is writable, use -gst_buffer_is_writable() to check that if needed. - - - %TRUE if the memory range is writable - - - - - a #GstBuffer. - - - - an index - - - - a length should not be 0 - - - - - - Retrieve the next #GstMeta after @current. If @state points -to %NULL, the first metadata is returned. - -@state will be updated with an opaque state pointer - - - The next #GstMeta or %NULL -when there are no more items. - - - - - a #GstBuffer - - - - an opaque state pointer - - - - - - Retrieve the next #GstMeta of type @meta_api_type after the current one -according to @state. If @state points to %NULL, the first metadata of -type @meta_api_type is returned. - -@state will be updated with an opaque state pointer - - - The next #GstMeta of type -@meta_api_type or %NULL when there are no more items. - - - - - a #GstBuffer - - - - an opaque state pointer - - - - only return #GstMeta of this type - - - - - - This function fills @info with the #GstMapInfo of all merged memory -blocks in @buffer. - -@flags describe the desired access of the memory. When @flags is -#GST_MAP_WRITE, @buffer should be writable (as returned from -gst_buffer_is_writable()). - -When @buffer is writable but the memory isn't, a writable copy will -automatically be created and returned. The readonly copy of the -buffer memory will then also be replaced with this writable copy. - -The memory in @info should be unmapped with gst_buffer_unmap() after -usage. - - - %TRUE if the map succeeded and @info contains valid data. - - - - - a #GstBuffer. - - - - info about the mapping - - - - flags for the mapping - - - - - - This function fills @info with the #GstMapInfo of @length merged memory blocks -starting at @idx in @buffer. When @length is -1, all memory blocks starting -from @idx are merged and mapped. - -@flags describe the desired access of the memory. When @flags is -#GST_MAP_WRITE, @buffer should be writable (as returned from -gst_buffer_is_writable()). - -When @buffer is writable but the memory isn't, a writable copy will -automatically be created and returned. The readonly copy of the buffer memory -will then also be replaced with this writable copy. - -The memory in @info should be unmapped with gst_buffer_unmap() after usage. - - - %TRUE if the map succeeded and @info contains valid -data. - - - - - a #GstBuffer. - - - - an index - - - - a length - - - - info about the mapping - - - - flags for the mapping - - - - - - Compare @size bytes starting from @offset in @buffer with the memory in @mem. - - - 0 if the memory is equal. - - - - - a #GstBuffer. - - - - the offset in @buffer - - - - the memory to compare - - - - - - the size to compare - - - - - - Fill @buf with @size bytes with @val starting from @offset. - - - The amount of bytes filled. This value can be lower than @size - when @buffer did not contain enough data. - - - - - a #GstBuffer. - - - - the offset in @buffer - - - - the value to set - - - - the size to set - - - - - - Get the amount of memory blocks that this buffer has. This amount is never -larger than what gst_buffer_get_max_memory() returns. - - - the number of memory blocks this buffer is made of. - - - - - a #GstBuffer. - - - - - - Get the memory block at @idx in @buffer. The memory block stays valid until -the memory block in @buffer is removed, replaced or merged, typically with -any call that modifies the memory in @buffer. - - - the #GstMemory at @idx. - - - - - a #GstBuffer. - - - - an index - - - - - - Prepend the memory block @mem to @buffer. This function takes -ownership of @mem and thus doesn't increase its refcount. - -This function is identical to gst_buffer_insert_memory() with an index of 0. -See gst_buffer_insert_memory() for more details. - - - - - - - a #GstBuffer. - - - - a #GstMemory. - - - - - - Increases the refcount of the given buffer by one. - -Note that the refcount affects the writability -of @buf and its metadata, see gst_buffer_is_writable(). -It is important to note that keeping additional references to -GstBuffer instances can potentially increase the number -of memcpy operations in a pipeline. - - - @buf - - - - - a #GstBuffer. - - - - - - Remove all the memory blocks in @buffer. - - - - - - - a #GstBuffer. - - - - - - Remove the memory block in @b at index @i. - - - - - - - a #GstBuffer. - - - - an index - - - - - - Remove @length memory blocks in @buffer starting from @idx. - -@length can be -1, in which case all memory starting from @idx is removed. - - - - - - - a #GstBuffer. - - - - an index - - - - a length - - - - - - Remove the metadata for @meta on @buffer. - - - %TRUE if the metadata existed and was removed, %FALSE if no such -metadata was on @buffer. - - - - - a #GstBuffer - - - - a #GstMeta - - - - - - Replaces all memory in @buffer with @mem. - - - - - - - a #GstBuffer. - - - - a #GstMemory - - - - - - Replaces the memory block at index @idx in @buffer with @mem. - - - - - - - a #GstBuffer. - - - - an index - - - - a #GstMemory - - - - - - Replaces @length memory blocks in @buffer starting at @idx with @mem. - -If @length is -1, all memory starting from @idx will be removed and -replaced with @mem. - -@buffer should be writable. - - - - - - - a #GstBuffer. - - - - an index - - - - a length should not be 0 - - - - a #GstMemory - - - - - - Set the offset and total size of the memory blocks in @buffer. - - - - - - - a #GstBuffer. - - - - the offset adjustment - - - - the new size or -1 to just adjust the offset - - - - - - Set the total size of the @length memory blocks starting at @idx in -@buffer - - - %TRUE if resizing succeeded, %FALSE otherwise. - - - - - a #GstBuffer. - - - - an index - - - - a length - - - - the offset adjustment - - - - the new size or -1 to just adjust the offset - - - - - - Sets one or more buffer flags on a buffer. - - - %TRUE if @flags were successfully set on buffer. - - - - - a #GstBuffer - - - - the #GstBufferFlags to set. - - - - - - Set the total size of the memory blocks in @buffer. - - - - - - - a #GstBuffer. - - - - the new size - - - - - - Release the memory previously mapped with gst_buffer_map(). - - - - - - - a #GstBuffer. - - - - a #GstMapInfo - - - - - - Decreases the refcount of the buffer. If the refcount reaches 0, the buffer -with the associated metadata and memory will be freed. - - - - - - - a #GstBuffer. - - - - - - Clears one or more buffer flags. - - - true if @flags is successfully cleared from buffer. - - - - - a #GstBuffer - - - - the #GstBufferFlags to clear - - - - - - Get the maximum amount of memory blocks that a buffer can hold. This is a -compile time constant that can be queried with the function. - -When more memory blocks are added, existing memory blocks will be merged -together to make room for the new block. - - - the maximum amount of memory blocks that a buffer can hold. - - - - - Modifies a pointer to a #GstBuffer to point to a different #GstBuffer. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -buffer is unreffed, the new is reffed). - -Either @nbuf or the #GstBuffer pointed to by @obuf may be %NULL. - - - %TRUE when @obuf was different from @nbuf. - - - - - pointer to a pointer to - a #GstBuffer to be replaced. - - - - pointer to a #GstBuffer that will - replace the buffer pointed to by @obuf. - - - - - - - A set of flags that can be provided to the gst_buffer_copy_into() -function to specify which items should be copied. - - copy nothing - - - flag indicating that buffer flags should be copied - - - flag indicating that buffer pts, dts, - duration, offset and offset_end should be copied - - - flag indicating that buffer meta should be - copied - - - flag indicating that buffer memory should be reffed - and appended to already existing memory. Unless the memory is marked as - NO_SHARE, no actual copy of the memory is made but it is simply reffed. - Add @GST_BUFFER_COPY_DEEP to force a real copy. - - - flag indicating that buffer memory should be - merged - - - flag indicating that memory should always be - copied instead of reffed (Since: 1.2) - - - - A set of buffer flags used to describe properties of a #GstBuffer. - - the buffer is live data and should be discarded in - the PAUSED state. - - - the buffer contains data that should be dropped - because it will be clipped against the segment - boundaries or because it does not contain data - that should be shown to the user. - - - the buffer marks a data discontinuity in the stream. - This typically occurs after a seek or a dropped buffer - from a live or network source. - - - the buffer timestamps might have a discontinuity - and this buffer is a good point to resynchronize. - - - the buffer data is corrupted. - - - the buffer contains a media specific marker. for - video this is the end of a frame boundary, for audio - this is the start of a talkspurt. - - - the buffer contains header information that is - needed to decode the following data. - - - the buffer has been created to fill a gap in the - stream and contains media neutral data (elements can - switch to optimized code path that ignores the buffer - content). - - - the buffer can be dropped without breaking the - stream, for example to reduce bandwidth. - - - this unit cannot be decoded independently. - - - this flag is set when memory of the buffer - is added/removed - - - Elements which write to disk or permanent - storage should ensure the data is synced after - writing the contents of this buffer. (Since: 1.6) - - - This buffer is important and should not be dropped. - This can be used to mark important buffers, e.g. to flag - RTP packets carrying keyframes or codec setup data for RTP - Forward Error Correction purposes, or to prevent still video - frames from being dropped by elements due to QoS. (Since: 1.14) - - - additional media specific flags can be added starting from - this flag. - - - - A function that will be called from gst_buffer_foreach_meta(). The @meta -field will point to a the reference of the meta. - -@buffer should not be modified from this callback. - -When this function returns %TRUE, the next meta will be -returned. When %FALSE is returned, gst_buffer_foreach_meta() will return. - -When @meta is set to %NULL, the item will be removed from the buffer. - - - %FALSE when gst_buffer_foreach_meta() should stop - - - - - a #GstBuffer - - - - a pointer to a #GstMeta - - - - user data passed to gst_buffer_foreach_meta() - - - - - - Buffer lists are an object containing a list of buffers. - -Buffer lists are created with gst_buffer_list_new() and filled with data -using a gst_buffer_list_insert(). - -Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is -interesting when multiple buffers need to be pushed in one go because it -can reduce the amount of overhead for pushing each buffer individually. - - - Creates a new, empty #GstBufferList. The caller is responsible for unreffing -the returned #GstBufferList. - -Free-function: gst_buffer_list_unref - - - the new #GstBufferList. gst_buffer_list_unref() - after usage. - - - - - Creates a new, empty #GstBufferList. The caller is responsible for unreffing -the returned #GstBufferList. The list will have @size space preallocated so -that memory reallocations can be avoided. - -Free-function: gst_buffer_list_unref - - - the new #GstBufferList. gst_buffer_list_unref() - after usage. - - - - - an initial reserved size - - - - - - Calculates the size of the data contained in buffer list by adding the -size of all buffers. - - - the size of the data contained in buffer list in bytes. - - - - - a #GstBufferList - - - - - - Create a shallow copy of the given buffer list. This will make a newly -allocated copy of the source list with copies of buffer pointers. The -refcount of buffers pointed to will be increased by one. - - - a new copy of @list. - - - - - a #GstBufferList - - - - - - Create a copy of the given buffer list. This will make a newly allocated -copy of the buffer that the source buffer list contains. - - - a new copy of @list. - - - - - a #GstBufferList - - - - - - Call @func with @data for each buffer in @list. - -@func can modify the passed buffer pointer or its contents. The return value -of @func define if this function returns or if the remaining buffers in -the list should be skipped. - - - %TRUE when @func returned %TRUE for each buffer in @list or when -@list is empty. - - - - - a #GstBufferList - - - - a #GstBufferListFunc to call - - - - user data passed to @func - - - - - - Get the buffer at @idx. - -You must make sure that @idx does not exceed the number of -buffers available. - - - the buffer at @idx in @group - or %NULL when there is no buffer. The buffer remains valid as - long as @list is valid and buffer is not removed from the list. - - - - - a #GstBufferList - - - - the index - - - - - - Gets the buffer at @idx, ensuring it is a writable buffer. - -You must make sure that @idx does not exceed the number of -buffers available. - - - the buffer at @idx in @group. - The returned buffer remains valid as long as @list is valid and - the buffer is not removed from the list. - - - - - a (writable) #GstBufferList - - - - the index - - - - - - Insert @buffer at @idx in @list. Other buffers are moved to make room for -this new buffer. - -A -1 value for @idx will append the buffer at the end. - - - - - - - a #GstBufferList - - - - the index - - - - a #GstBuffer - - - - - - Returns the number of buffers in @list. - - - the number of buffers in the buffer list - - - - - a #GstBufferList - - - - - - Increases the refcount of the given buffer list by one. - -Note that the refcount affects the writability of @list and its data, see -gst_buffer_list_make_writable(). It is important to note that keeping -additional references to GstBufferList instances can potentially increase -the number of memcpy operations in a pipeline. - - - @list - - - - - a #GstBufferList - - - - - - Remove @length buffers starting from @idx in @list. The following buffers -are moved to close the gap. - - - - - - - a #GstBufferList - - - - the index - - - - the amount to remove - - - - - - Decreases the refcount of the buffer list. If the refcount reaches 0, the -buffer list will be freed. - - - - - - - a #GstBufferList - - - - - - - A function that will be called from gst_buffer_list_foreach(). The @buffer -field will point to a the reference of the buffer at @idx. - -When this function returns %TRUE, the next buffer will be -returned. When %FALSE is returned, gst_buffer_list_foreach() will return. - -When @buffer is set to %NULL, the item will be removed from the bufferlist. -When @buffer has been made writable, the new buffer reference can be assigned -to @buffer. This function is responsible for unreffing the old buffer when -removing or modifying. - - - %FALSE when gst_buffer_list_foreach() should stop - - - - - pointer the buffer - - - - the index of @buffer - - - - user data passed to gst_buffer_list_foreach() - - - - - - A #GstBufferPool is an object that can be used to pre-allocate and recycle -buffers of the same size and with the same properties. - -A #GstBufferPool is created with gst_buffer_pool_new(). - -Once a pool is created, it needs to be configured. A call to -gst_buffer_pool_get_config() returns the current configuration structure from -the pool. With gst_buffer_pool_config_set_params() and -gst_buffer_pool_config_set_allocator() the bufferpool parameters and -allocator can be configured. Other properties can be configured in the pool -depending on the pool implementation. - -A bufferpool can have extra options that can be enabled with -gst_buffer_pool_config_add_option(). The available options can be retrieved -with gst_buffer_pool_get_options(). Some options allow for additional -configuration properties to be set. - -After the configuration structure has been configured, -gst_buffer_pool_set_config() updates the configuration in the pool. This can -fail when the configuration structure is not accepted. - -After the a pool has been configured, it can be activated with -gst_buffer_pool_set_active(). This will preallocate the configured resources -in the pool. - -When the pool is active, gst_buffer_pool_acquire_buffer() can be used to -retrieve a buffer from the pool. - -Buffers allocated from a bufferpool will automatically be returned to the -pool with gst_buffer_pool_release_buffer() when their refcount drops to 0. - -The bufferpool can be deactivated again with gst_buffer_pool_set_active(). -All further gst_buffer_pool_acquire_buffer() calls will return an error. When -all buffers are returned to the pool they will be freed. - -Use gst_object_unref() to release the reference to a bufferpool. If the -refcount of the pool reaches 0, the pool will be freed. - - - Creates a new #GstBufferPool instance. - - - a new #GstBufferPool instance - - - - - Enabled the option in @config. This will instruct the @bufferpool to enable -the specified option on the buffers that it allocates. - -The supported options by @pool can be retrieved with gst_buffer_pool_get_options(). - - - - - - - a #GstBufferPool configuration - - - - an option to add - - - - - - Get the @allocator and @params from @config. - - - %TRUE, if the values are set. - - - - - a #GstBufferPool configuration - - - - a #GstAllocator, or %NULL - - - - #GstAllocationParams, or %NULL - - - - - - Parse an available @config and get the option at @index of the options API -array. - - - a #gchar of the option at @index. - - - - - a #GstBufferPool configuration - - - - position in the option array to read - - - - - - Get the configuration values from @config. - - - %TRUE if all parameters could be fetched. - - - - - a #GstBufferPool configuration - - - - the caps of buffers - - - - the size of each buffer, not including prefix and padding - - - - the minimum amount of buffers to allocate. - - - - the maximum amount of buffers to allocate or 0 for unlimited. - - - - - - Check if @config contains @option. - - - %TRUE if the options array contains @option. - - - - - a #GstBufferPool configuration - - - - an option - - - - - - Retrieve the number of values currently stored in the options array of the -@config structure. - - - the options array size as a #guint. - - - - - a #GstBufferPool configuration - - - - - - Set the @allocator and @params on @config. - -One of @allocator and @params can be %NULL, but not both. When @allocator -is %NULL, the default allocator of the pool will use the values in @param -to perform its allocation. When @param is %NULL, the pool will use the -provided @allocator with its default #GstAllocationParams. - -A call to gst_buffer_pool_set_config() can update the allocator and params -with the values that it is able to do. Some pools are, for example, not able -to operate with different allocators or cannot allocate with the values -specified in @params. Use gst_buffer_pool_get_config() to get the currently -used values. - - - - - - - a #GstBufferPool configuration - - - - a #GstAllocator - - - - #GstAllocationParams - - - - - - Configure @config with the given parameters. - - - - - - - a #GstBufferPool configuration - - - - caps for the buffers - - - - the size of each buffer, not including prefix and padding - - - - the minimum amount of buffers to allocate. - - - - the maximum amount of buffers to allocate or 0 for unlimited. - - - - - - Validate that changes made to @config are still valid in the context of the -expected parameters. This function is a helper that can be used to validate -changes made by a pool to a config when gst_buffer_pool_set_config() -returns %FALSE. This expects that @caps haven't changed and that -@min_buffers aren't lower then what we initially expected. -This does not check if options or allocator parameters are still valid, -won't check if size have changed, since changing the size is valid to adapt -padding. - - - %TRUE, if the parameters are valid in this context. - - - - - a #GstBufferPool configuration - - - - the excepted caps of buffers - - - - the expected size of each buffer, not including prefix and padding - - - - the expected minimum amount of buffers to allocate. - - - - the expect maximum amount of buffers to allocate or 0 for unlimited. - - - - - - Acquire a buffer from @pool. @buffer should point to a memory location that -can hold a pointer to the new buffer. - -@params can be %NULL or contain optional parameters to influence the -allocation. - - - a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is -inactive. - - - - - a #GstBufferPool - - - - a location for a #GstBuffer - - - - parameters. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get a %NULL terminated array of string with supported bufferpool options for -@pool. An option would typically be enabled with -gst_buffer_pool_config_add_option(). - - - a %NULL terminated array - of strings. - - - - - - - a #GstBufferPool - - - - - - Release @buffer to @pool. @buffer should have previously been allocated from -@pool with gst_buffer_pool_acquire_buffer(). - -This function is usually called automatically when the last ref on @buffer -disappears. - - - - - - - a #GstBufferPool - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - - Set the configuration of the pool. If the pool is already configured, and -the configuration haven't change, this function will return %TRUE. If the -pool is active, this method will return %FALSE and active configuration -will remain. Buffers allocated form this pool must be returned or else this -function will do nothing and return %FALSE. - -@config is a #GstStructure that contains the configuration parameters for -the pool. A default and mandatory set of parameters can be configured with -gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator() -and gst_buffer_pool_config_add_option(). - -If the parameters in @config can not be set exactly, this function returns -%FALSE and will try to update as much state as possible. The new state can -then be retrieved and refined with gst_buffer_pool_get_config(). - -This function takes ownership of @config. - - - %TRUE when the configuration could be set. - - - - - a #GstBufferPool - - - - a #GstStructure - - - - - - - - - - - - - - - - - - - - - - - - - - - - Acquire a buffer from @pool. @buffer should point to a memory location that -can hold a pointer to the new buffer. - -@params can be %NULL or contain optional parameters to influence the -allocation. - - - a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is -inactive. - - - - - a #GstBufferPool - - - - a location for a #GstBuffer - - - - parameters. - - - - - - Get a copy of the current configuration of the pool. This configuration -can either be modified and used for the gst_buffer_pool_set_config() call -or it must be freed after usage. - - - a copy of the current configuration of @pool. use -gst_structure_free() after usage or gst_buffer_pool_set_config(). - - - - - a #GstBufferPool - - - - - - Get a %NULL terminated array of string with supported bufferpool options for -@pool. An option would typically be enabled with -gst_buffer_pool_config_add_option(). - - - a %NULL terminated array - of strings. - - - - - - - a #GstBufferPool - - - - - - Check if the bufferpool supports @option. - - - %TRUE if the buffer pool contains @option. - - - - - a #GstBufferPool - - - - an option - - - - - - Check if @pool is active. A pool can be activated with the -gst_buffer_pool_set_active() call. - - - %TRUE when the pool is active. - - - - - a #GstBufferPool - - - - - - Release @buffer to @pool. @buffer should have previously been allocated from -@pool with gst_buffer_pool_acquire_buffer(). - -This function is usually called automatically when the last ref on @buffer -disappears. - - - - - - - a #GstBufferPool - - - - a #GstBuffer - - - - - - Control the active state of @pool. When the pool is inactive, new calls to -gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING. - -Activating the bufferpool will preallocate all resources in the pool based on -the configuration of the pool. - -Deactivating will free the resources again when there are no outstanding -buffers. When there are outstanding buffers, they will be freed as soon as -they are all returned to the pool. - - - %FALSE when the pool was not configured or when preallocation of the -buffers failed. - - - - - a #GstBufferPool - - - - the new active state - - - - - - Set the configuration of the pool. If the pool is already configured, and -the configuration haven't change, this function will return %TRUE. If the -pool is active, this method will return %FALSE and active configuration -will remain. Buffers allocated form this pool must be returned or else this -function will do nothing and return %FALSE. - -@config is a #GstStructure that contains the configuration parameters for -the pool. A default and mandatory set of parameters can be configured with -gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator() -and gst_buffer_pool_config_add_option(). - -If the parameters in @config can not be set exactly, this function returns -%FALSE and will try to update as much state as possible. The new state can -then be retrieved and refined with gst_buffer_pool_get_config(). - -This function takes ownership of @config. - - - %TRUE when the configuration could be set. - - - - - a #GstBufferPool - - - - a #GstStructure - - - - - - Enable or disable the flushing state of a @pool without freeing or -allocating buffers. - - - - - - - a #GstBufferPool - - - - whether to start or stop flushing - - - - - - - - - - - - - - - - - - - - - Additional flags to control the allocation of a buffer - - no flags - - - buffer is keyframe - - - when the bufferpool is empty, acquire_buffer -will by default block until a buffer is released into the pool again. Setting -this flag makes acquire_buffer return #GST_FLOW_EOS instead of blocking. - - - buffer is discont - - - last flag, subclasses can use private flags - starting from this value. - - - - Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the -allocation of the buffer. - -The default implementation ignores the @start and @stop members but other -implementations can use this extra information to decide what buffer to -return. - - - the format of @start and @stop - - - - the start position - - - - the stop position - - - - additional flags - - - - - - - - - - The GstBufferPool class. - - - Object parent class - - - - - - - a %NULL terminated array - of strings. - - - - - - - a #GstBufferPool - - - - - - - - - - %TRUE when the configuration could be set. - - - - - a #GstBufferPool - - - - a #GstStructure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is -inactive. - - - - - a #GstBufferPool - - - - a location for a #GstBuffer - - - - parameters. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstBufferPool - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The different types of buffering methods. - - a small amount of data is buffered - - - the stream is being downloaded - - - the stream is being downloaded in a ringbuffer - - - the stream is a live stream - - - - The #GstBus is an object responsible for delivering #GstMessage packets in -a first-in first-out way from the streaming threads (see #GstTask) to the -application. - -Since the application typically only wants to deal with delivery of these -messages from one thread, the GstBus will marshall the messages between -different threads. This is important since the actual streaming of media -is done in another thread than the application. - -The GstBus provides support for #GSource based notifications. This makes it -possible to handle the delivery in the glib mainloop. - -The #GSource callback function gst_bus_async_signal_func() can be used to -convert all bus messages into signal emissions. - -A message is posted on the bus with the gst_bus_post() method. With the -gst_bus_peek() and gst_bus_pop() methods one can look at or retrieve a -previously posted message. - -The bus can be polled with the gst_bus_poll() method. This methods blocks -up to the specified timeout value until one of the specified messages types -is posted on the bus. The application can then gst_bus_pop() the messages -from the bus to handle them. -Alternatively the application can register an asynchronous bus function -using gst_bus_add_watch_full() or gst_bus_add_watch(). This function will -install a #GSource in the default glib main loop and will deliver messages -a short while after they have been posted. Note that the main loop should -be running for the asynchronous callbacks. - -It is also possible to get messages from the bus without any thread -marshalling with the gst_bus_set_sync_handler() method. This makes it -possible to react to a message in the same thread that posted the -message on the bus. This should only be used if the application is able -to deal with messages from different threads. - -Every #GstPipeline has one bus. - -Note that a #GstPipeline will set its bus into flushing state when changing -from READY to NULL state. - - - Creates a new #GstBus instance. - - - a new #GstBus instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Adds a bus signal watch to the default main context with the default priority -(%G_PRIORITY_DEFAULT). It is also possible to use a non-default -main context set up using g_main_context_push_thread_default() (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -After calling this statement, the bus will emit the "message" signal for each -message posted on the bus. - -This function may be called multiple times. To clean up, the caller is -responsible for calling gst_bus_remove_signal_watch() as many times as this -function is called. - -MT safe. - - - - - - - a #GstBus on which you want to receive the "message" signal - - - - - - Adds a bus signal watch to the default main context with the given @priority -(e.g. %G_PRIORITY_DEFAULT). It is also possible to use a non-default main -context set up using g_main_context_push_thread_default() -(before one had to create a bus watch source and attach it to the desired -main context 'manually'). - -After calling this statement, the bus will emit the "message" signal for each -message posted on the bus when the main loop is running. - -This function may be called multiple times. To clean up, the caller is -responsible for calling gst_bus_remove_signal_watch() as many times as this -function is called. - -There can only be a single bus watch per bus, you must remove any signal -watch before you can set another type of watch. - -MT safe. - - - - - - - a #GstBus on which you want to receive the "message" signal - - - - The priority of the watch. - - - - - - Adds a bus watch to the default main context with the default priority -(%G_PRIORITY_DEFAULT). It is also possible to use a non-default main -context set up using g_main_context_push_thread_default() (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -This function is used to receive asynchronous messages in the main loop. -There can only be a single bus watch per bus, you must remove it before you -can set a new one. - -The bus watch will only work if a GLib main loop is being run. - -The watch can be removed using gst_bus_remove_watch() or by returning %FALSE -from @func. If the watch was added to the default main context it is also -possible to remove the watch using g_source_remove(). - -The bus watch will take its own reference to the @bus, so it is safe to unref -@bus using gst_object_unref() after setting the bus watch. - -MT safe. - - - The event source id or 0 if @bus already got an event source. - - - - - a #GstBus to create the watch for - - - - A function to call when a message is received. - - - - user data passed to @func. - - - - - - Adds a bus watch to the default main context with the given @priority (e.g. -%G_PRIORITY_DEFAULT). It is also possible to use a non-default main -context set up using g_main_context_push_thread_default() (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -This function is used to receive asynchronous messages in the main loop. -There can only be a single bus watch per bus, you must remove it before you -can set a new one. - -The bus watch will only work if a GLib main loop is being run. - -When @func is called, the message belongs to the caller; if you want to -keep a copy of it, call gst_message_ref() before leaving @func. - -The watch can be removed using gst_bus_remove_watch() or by returning %FALSE -from @func. If the watch was added to the default main context it is also -possible to remove the watch using g_source_remove(). - -The bus watch will take its own reference to the @bus, so it is safe to unref -@bus using gst_object_unref() after setting the bus watch. - -MT safe. - - - The event source id or 0 if @bus already got an event source. - - - - - a #GstBus to create the watch for. - - - - The priority of the watch. - - - - A function to call when a message is received. - - - - user data passed to @func. - - - - the function to call when the source is removed. - - - - - - A helper #GstBusFunc that can be used to convert all asynchronous messages -into signals. - - - %TRUE - - - - - a #GstBus - - - - the #GstMessage received - - - - user data - - - - - - Create watch for this bus. The GSource will be dispatched whenever -a message is on the bus. After the GSource is dispatched, the -message is popped off the bus and unreffed. - - - a #GSource that can be added to a mainloop. - - - - - a #GstBus to create the watch for - - - - - - Instructs GStreamer to stop emitting the "sync-message" signal for this bus. -See gst_bus_enable_sync_message_emission() for more information. - -In the event that multiple pieces of code have called -gst_bus_enable_sync_message_emission(), the sync-message emissions will only -be stopped after all calls to gst_bus_enable_sync_message_emission() were -"cancelled" by calling this function. In this way the semantics are exactly -the same as gst_object_ref() that which calls enable should also call -disable. - -MT safe. - - - - - - - a #GstBus on which you previously called -gst_bus_enable_sync_message_emission() - - - - - - Instructs GStreamer to emit the "sync-message" signal after running the bus's -sync handler. This function is here so that code can ensure that they can -synchronously receive messages without having to affect what the bin's sync -handler is. - -This function may be called multiple times. To clean up, the caller is -responsible for calling gst_bus_disable_sync_message_emission() as many times -as this function is called. - -While this function looks similar to gst_bus_add_signal_watch(), it is not -exactly the same -- this function enables *synchronous* emission of -signals when messages arrive; gst_bus_add_signal_watch() adds an idle callback -to pop messages off the bus *asynchronously*. The sync-message signal -comes from the thread of whatever object posted the message; the "message" -signal is marshalled to the main thread via the main loop. - -MT safe. - - - - - - - a #GstBus on which you want to receive the "sync-message" signal - - - - - - Gets the file descriptor from the bus which can be used to get notified about -messages being available with functions like g_poll(), and allows integration -into other event loops based on file descriptors. -Whenever a message is available, the POLLIN / %G_IO_IN event is set. - -Warning: NEVER read or write anything to the returned fd but only use it -for getting notifications via g_poll() or similar and then use the normal -GstBus API, e.g. gst_bus_pop(). - - - - - - - A #GstBus - - - - A GPollFD to fill - - - - - - Check if there are pending messages on the bus that -should be handled. - - - %TRUE if there are messages on the bus to be handled, %FALSE -otherwise. - -MT safe. - - - - - a #GstBus to check - - - - - - Peek the message on the top of the bus' queue. The message will remain -on the bus' message queue. A reference is returned, and needs to be unreffed -by the caller. - - - the #GstMessage that is on the - bus, or %NULL if the bus is empty. - -MT safe. - - - - - a #GstBus - - - - - - Poll the bus for messages. Will block while waiting for messages to come. -You can specify a maximum time to poll with the @timeout parameter. If -@timeout is negative, this function will block indefinitely. - -All messages not in @events will be popped off the bus and will be ignored. -It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the -@events mask - -Because poll is implemented using the "message" signal enabled by -gst_bus_add_signal_watch(), calling gst_bus_poll() will cause the "message" -signal to be emitted for every message that poll sees. Thus a "message" -signal handler will see the same messages that this function sees -- neither -will steal messages from the other. - -This function will run a main loop from the default main context when -polling. - -You should never use this function, since it is pure evil. This is -especially true for GUI applications based on Gtk+ or Qt, but also for any -other non-trivial application that uses the GLib main loop. As this function -runs a GLib main loop, any callback attached to the default GLib main -context may be invoked. This could be timeouts, GUI events, I/O events etc.; -even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks -may do things you do not expect, e.g. destroy the main application window or -some other resource; change other application state; display a dialog and -run another main loop until the user clicks it away. In short, using this -function may add a lot of complexity to your code through unexpected -re-entrancy and unexpected changes to your application's state. - -For 0 timeouts use gst_bus_pop_filtered() instead of this function; for -other short timeouts use gst_bus_timed_pop_filtered(); everything else is -better handled by setting up an asynchronous bus watch and doing things -from there. - - - the message that was received, - or %NULL if the poll timed out. The message is taken from the - bus and needs to be unreffed with gst_message_unref() after - usage. - - - - - a #GstBus - - - - a mask of #GstMessageType, representing the set of message types to -poll for (note special handling of extended message types below) - - - - the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll -indefinitely. - - - - - - Get a message from the bus. - - - the #GstMessage that is on the - bus, or %NULL if the bus is empty. The message is taken from - the bus and needs to be unreffed with gst_message_unref() after - usage. - -MT safe. - - - - - a #GstBus to pop - - - - - - Get a message matching @type from the bus. Will discard all messages on -the bus that do not match @type and that have been posted before the first -message that does match @type. If there is no message matching @type on -the bus, all messages will be discarded. It is not possible to use message -enums beyond #GST_MESSAGE_EXTENDED in the @events mask. - - - the next #GstMessage matching - @type that is on the bus, or %NULL if the bus is empty or there - is no message matching @type. The message is taken from the bus - and needs to be unreffed with gst_message_unref() after usage. - -MT safe. - - - - - a #GstBus to pop - - - - message types to take into account - - - - - - Post a message on the given bus. Ownership of the message -is taken by the bus. - - - %TRUE if the message could be posted, %FALSE if the bus is flushing. - -MT safe. - - - - - a #GstBus to post on - - - - the #GstMessage to post - - - - - - Removes a signal watch previously added with gst_bus_add_signal_watch(). - -MT safe. - - - - - - - a #GstBus you previously added a signal watch to - - - - - - Removes an installed bus watch from @bus. - - - %TRUE on success or %FALSE if @bus has no event source. - - - - - a #GstBus to remove the watch from. - - - - - - If @flushing, flush out and unref any messages queued in the bus. Releases -references to the message origin objects. Will flush future messages until -gst_bus_set_flushing() sets @flushing to %FALSE. - -MT safe. - - - - - - - a #GstBus - - - - whether or not to flush the bus - - - - - - Sets the synchronous handler on the bus. The function will be called -every time a new message is posted on the bus. Note that the function -will be called in the same thread context as the posting object. This -function is usually only called by the creator of the bus. Applications -should handle messages asynchronously using the gst_bus watch and poll -functions. - -Before 1.16.3 it was not possible to replace an existing handler and -clearing an existing handler with %NULL was not thread-safe. - - - - - - - a #GstBus to install the handler on - - - - The handler function to install - - - - User data that will be sent to the handler function. - - - - called when @user_data becomes unused - - - - - - A helper GstBusSyncHandler that can be used to convert all synchronous -messages into signals. - - - GST_BUS_PASS - - - - - a #GstBus - - - - the #GstMessage received - - - - user data - - - - - - Get a message from the bus, waiting up to the specified timeout. - -If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is -#GST_CLOCK_TIME_NONE, this function will block forever until a message was -posted on the bus. - - - the #GstMessage that is on the - bus after the specified timeout or %NULL if the bus is empty - after the timeout expired. The message is taken from the bus - and needs to be unreffed with gst_message_unref() after usage. - -MT safe. - - - - - a #GstBus to pop - - - - a timeout - - - - - - Get a message from the bus whose type matches the message type mask @types, -waiting up to the specified timeout (and discarding any messages that do not -match the mask provided). - -If @timeout is 0, this function behaves like gst_bus_pop_filtered(). If -@timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a -matching message was posted on the bus. - - - a #GstMessage matching the - filter in @types, or %NULL if no matching message was found on - the bus until the timeout expired. The message is taken from - the bus and needs to be unreffed with gst_message_unref() after - usage. - -MT safe. - - - - - a #GstBus to pop from - - - - a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever - - - - message types to take into account, GST_MESSAGE_ANY for any type - - - - - - - - - - - - - - - - - - - - A message has been posted on the bus. This signal is emitted from a -GSource added to the mainloop. this signal will only be emitted when -there is a mainloop running. - - - - - - the message that has been posted asynchronously - - - - - - A message has been posted on the bus. This signal is emitted from the -thread that posted the message so one has to be careful with locking. - -This signal will not be emitted by default, you have to call -gst_bus_enable_sync_message_emission() before. - - - - - - the message that has been posted synchronously - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The standard flags that a bus may have. - - The bus is currently dropping all messages - - - offset to define more flags - - - - Specifies the type of function passed to gst_bus_add_watch() or -gst_bus_add_watch_full(), which is called from the mainloop when a message -is available on the bus. - -The message passed to the function will be unreffed after execution of this -function so it should not be freed in the function. - -Note that this function is used as a GSourceFunc which means that returning -%FALSE will remove the GSource from the mainloop. - - - %FALSE if the event source should be removed. - - - - - the #GstBus that sent the message - - - - the #GstMessage - - - - user data that has been given, when registering the handler - - - - - - - - - Handler will be invoked synchronously, when a new message has been injected -into the bus. This function is mostly used internally. Only one sync handler -can be attached to a given bus. - -If the handler returns GST_BUS_DROP, it should unref the message, else the -message should not be unreffed by the sync handler. - - - #GstBusSyncReply stating what to do with the message - - - - - the #GstBus that sent the message - - - - the #GstMessage - - - - user data that has been given, when registering the handler - - - - - - The result values for a GstBusSyncHandler. - - drop the message - - - pass the message to the async queue - - - pass message to async queue, continue if message is handled - - - - Just call the parent handler. This assumes that there is a variable -named parent_class that points to the (duh!) parent class. Note that -this macro is not to be used with things that return something, use -the _WITH_DEFAULT version for that - - - - the name of the class cast macro for the parent type - - - name of the function to call - - - arguments enclosed in '( )' - - - - - Same as GST_CALL_PARENT(), but in case there is no implementation, it -evaluates to @def_return. - - - - the name of the class cast macro for the parent type - - - name of the function to call - - - arguments enclosed in '( )' - - - default result - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A flags word containing #GstCapsFlags flags set on this caps. - - - - a #GstCaps. - - - - - Gives the status of a specific flag on a caps. - - - - a #GstCaps. - - - the #GstCapsFlags to check. - - - - - Sets a caps flag on a caps. - - - - a #GstCaps. - - - the #GstCapsFlags to set. - - - - - Clears a caps flag. - - - - a #GstCaps. - - - the #GstCapsFlags to clear. - - - - - Convenience macro that checks if the number of structures in the given caps -is exactly one. - - - - the #GstCaps instance to check - - - - - Get access to the reference count field of the caps - - - - a #GstCaps - - - - - Get the reference count value of the caps. - - - - a #GstCaps - - - - - Output a hexdump of @data in the given category. - -There is no need to finish the end of the message string with a newline -character, a newline character will be added automatically. - - - - category to use - - - message string to log with the data - - - pointer to the data to output - - - length of the data to output - - - - - Output a hexdump of @data relating to the given object in the given -category. - -There is no need to finish the end of the message string with a newline -character, a newline character will be added automatically. - - - - category to use - - - the #GObject the message belongs to - - - message string to log with the data - - - pointer to the data to output - - - length of the data to output - - - - - Check whether a GStreamer version equal to or greater than -major.minor.micro is present. - - - - a number indicating the major version - - - a number indicating the minor version - - - a number indicating the micro version - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Calculate a difference between two clock times as a #GstClockTimeDiff. -The difference is calculated as @e - @s. - - - - the first time - - - the second time - - - - - Cast to a clock entry - - - - the entry to cast - - - - - Get the owner clock of the entry - Use gst_clock_id_get_clock() instead. - - - - the entry to query - - - - - Get the interval of this periodic entry - - - - the entry to query - - - - - The status of the entry - - - - the entry to query - - - - - Get the requested time of this entry - - - - the entry to query - - - - - Get the type of the clock entry - - - - the entry to query - - - - - Gets the #GstClockFlags clock flags. - - - - the clock to query - - - - - - - - - - - - Tests if a given #GstClockTimeDiff of #gint64 represents a valid defined time. - - - - signed clock time to validate - - - - - Tests if a given #GstClockTime represents a valid defined time. - - - - clock time to validate - - - - - Constant to define an undefined clock time. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Caps (capabilities) are lightweight refcounted objects describing media types. -They are composed of an array of #GstStructure. - -Caps are exposed on #GstPadTemplate to describe all possible types a -given pad can handle. They are also stored in the #GstRegistry along with -a description of the #GstElement. - -Caps are exposed on the element pads using the gst_pad_query_caps() pad -function. This function describes the possible types that the pad can -handle or produce at runtime. - -A #GstCaps can be constructed with the following code fragment: -|[<!-- language="C" --> - GstCaps *caps = gst_caps_new_simple ("video/x-raw", - "format", G_TYPE_STRING, "I420", - "framerate", GST_TYPE_FRACTION, 25, 1, - "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, - "width", G_TYPE_INT, 320, - "height", G_TYPE_INT, 240, - NULL); -]| - -A #GstCaps is fixed when it has no properties with ranges or lists. Use -gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a -caps event to notify downstream elements of the current media type. - -Various methods exist to work with the media types such as subtracting -or intersecting. - -Be aware that the current #GstCaps / #GstStructure serialization into string -has limited support for nested #GstCaps / #GstStructure fields. It can only -support one level of nesting. Using more levels will lead to unexpected -behavior when using serialization features, such as gst_caps_to_string() or -gst_value_serialize() and their counterparts. - - - the parent type - - - - Creates a new #GstCaps that indicates that it is compatible with -any media format. - - - the new #GstCaps - - - - - Creates a new #GstCaps that is empty. That is, the returned -#GstCaps contains no media formats. -The #GstCaps is guaranteed to be writable. -Caller is responsible for unreffing the returned caps. - - - the new #GstCaps - - - - - Creates a new #GstCaps that contains one #GstStructure with name -@media_type. -Caller is responsible for unreffing the returned caps. - - - the new #GstCaps - - - - - the media type of the structure - - - - - - Creates a new #GstCaps and adds all the structures listed as -arguments. The list must be %NULL-terminated. The structures -are not copied; the returned #GstCaps owns the structures. - - - the new #GstCaps - - - - - the first structure to add - - - - additional structures to add - - - - - - Creates a new #GstCaps and adds all the structures listed as -arguments. The list must be %NULL-terminated. The structures -are not copied; the returned #GstCaps owns the structures. - - - the new #GstCaps - - - - - the first structure to add - - - - additional structures to add - - - - - - Creates a new #GstCaps that contains one #GstStructure. The -structure is defined by the arguments, which have the same format -as gst_structure_new(). -Caller is responsible for unreffing the returned caps. - - - the new #GstCaps - - - - - the media type of the structure - - - - first field to set - - - - additional arguments - - - - - - Appends the structures contained in @caps2 to @caps1. The structures in -@caps2 are not copied -- they are transferred to @caps1, and then @caps2 is -freed. If either caps is ANY, the resulting caps will be ANY. - - - - - - - the #GstCaps that will be appended to - - - - the #GstCaps to append - - - - - - Appends @structure to @caps. The structure is not copied; @caps -becomes the owner of @structure. - - - - - - - the #GstCaps that will be appended to - - - - the #GstStructure to append - - - - - - Appends @structure with @features to @caps. The structure is not copied; @caps -becomes the owner of @structure. - - - - - - - the #GstCaps that will be appended to - - - - the #GstStructure to append - - - - the #GstCapsFeatures to append - - - - - - Tries intersecting @caps1 and @caps2 and reports whether the result would not -be empty - - - %TRUE if intersection would be not empty - - - - - a #GstCaps to intersect - - - - a #GstCaps to intersect - - - - - - Creates a new #GstCaps as a copy of the old @caps. The new caps will have a -refcount of 1, owned by the caller. The structures are copied as well. - -Note that this function is the semantic equivalent of a gst_caps_ref() -followed by a gst_caps_make_writable(). If you only want to hold on to a -reference to the data, you should use gst_caps_ref(). - -When you are finished with the caps, call gst_caps_unref() on it. - - - the new #GstCaps - - - - - a #GstCaps. - - - - - - Creates a new #GstCaps and appends a copy of the nth structure -contained in @caps. - - - the new #GstCaps - - - - - the #GstCaps to copy - - - - the nth structure to copy - - - - - - Calls the provided function once for each structure and caps feature in the -#GstCaps. In contrast to gst_caps_foreach(), the function may modify the -structure and features. In contrast to gst_caps_filter_and_map_in_place(), -the structure and features are removed from the caps if %FALSE is returned -from the function. -The caps must be mutable. - - - - - - - a #GstCaps - - - - a function to call for each field - - - - private data - - - - - - Modifies the given @caps into a representation with only fixed -values. First the caps will be truncated and then the first structure will be -fixated with gst_structure_fixate(). - -This function takes ownership of @caps and will call gst_caps_make_writable() -on it so you must not use @caps afterwards unless you keep an additional -reference to it with gst_caps_ref(). - -Note that it is not guaranteed that the returned caps have exactly one -structure. If @caps are empty caps then then returned caps will be -the empty too and contain no structure at all. - -Calling this function with any caps is not allowed. - - - the fixated caps - - - - - a #GstCaps to fixate - - - - - - Calls the provided function once for each structure and caps feature in the -#GstCaps. The function must not modify the fields. -Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place(). - - - %TRUE if the supplied function returns %TRUE for each call, -%FALSE otherwise. - - - - - a #GstCaps - - - - a function to call for each field - - - - private data - - - - - - Finds the features in @caps that has the index @index, and -returns it. - -WARNING: This function takes a const GstCaps *, but returns a -non-const GstCapsFeatures *. This is for programming convenience -- -the caller should be aware that structures inside a constant -#GstCaps should not be modified. However, if you know the caps -are writable, either because you have just copied them or made -them writable with gst_caps_make_writable(), you may modify the -features returned in the usual way, e.g. with functions like -gst_caps_features_add(). - -You do not need to free or unref the structure returned, it -belongs to the #GstCaps. - - - a pointer to the #GstCapsFeatures - corresponding to @index - - - - - a #GstCaps - - - - the index of the structure - - - - - - Gets the number of structures contained in @caps. - - - the number of structures that @caps contains - - - - - a #GstCaps - - - - - - Finds the structure in @caps that has the index @index, and -returns it. - -WARNING: This function takes a const GstCaps *, but returns a -non-const GstStructure *. This is for programming convenience -- -the caller should be aware that structures inside a constant -#GstCaps should not be modified. However, if you know the caps -are writable, either because you have just copied them or made -them writable with gst_caps_make_writable(), you may modify the -structure returned in the usual way, e.g. with functions like -gst_structure_set(). - -You do not need to free or unref the structure returned, it -belongs to the #GstCaps. - - - a pointer to the #GstStructure corresponding - to @index - - - - - a #GstCaps - - - - the index of the structure - - - - - - Creates a new #GstCaps that contains all the formats that are common -to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode. - - - the new #GstCaps - - - - - a #GstCaps to intersect - - - - a #GstCaps to intersect - - - - - - Creates a new #GstCaps that contains all the formats that are common -to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode -used. - - - the new #GstCaps - - - - - a #GstCaps to intersect - - - - a #GstCaps to intersect - - - - The intersection algorithm/mode to use - - - - - - A given #GstCaps structure is always compatible with another if -every media format that is in the first is also contained in the -second. That is, @caps1 is a subset of @caps2. - - - %TRUE if @caps1 is a subset of @caps2. - - - - - the #GstCaps to test - - - - the #GstCaps to test - - - - - - Determines if @caps represents any media format. - - - %TRUE if @caps represents any format. - - - - - the #GstCaps to test - - - - - - Determines if @caps represents no media formats. - - - %TRUE if @caps represents no formats. - - - - - the #GstCaps to test - - - - - - Checks if the given caps represent the same set of caps. - - - %TRUE if both caps are equal. - - - - - a #GstCaps - - - - another #GstCaps - - - - - - Tests if two #GstCaps are equal. This function only works on fixed -#GstCaps. - - - %TRUE if the arguments represent the same format - - - - - the #GstCaps to test - - - - the #GstCaps to test - - - - - - Fixed #GstCaps describe exactly one format, that is, they have exactly -one structure, and each field in the structure describes a fixed type. -Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. - - - %TRUE if @caps is fixed - - - - - the #GstCaps to test - - - - - - Checks if the given caps are exactly the same set of caps. - - - %TRUE if both caps are strictly equal. - - - - - a #GstCaps - - - - another #GstCaps - - - - - - Checks if all caps represented by @subset are also represented by @superset. - - - %TRUE if @subset is a subset of @superset - - - - - a #GstCaps - - - - a potentially greater #GstCaps - - - - - - Checks if @structure is a subset of @caps. See gst_caps_is_subset() -for more information. - - - %TRUE if @structure is a subset of @caps - - - - - a #GstCaps - - - - a potential #GstStructure subset of @caps - - - - - - Checks if @structure is a subset of @caps. See gst_caps_is_subset() -for more information. - - - %TRUE if @structure is a subset of @caps - - - - - a #GstCaps - - - - a potential #GstStructure subset of @caps - - - - a #GstCapsFeatures for @structure - - - - - - Calls the provided function once for each structure and caps feature in the -#GstCaps. In contrast to gst_caps_foreach(), the function may modify but not -delete the structures and features. The caps must be mutable. - - - %TRUE if the supplied function returns %TRUE for each call, -%FALSE otherwise. - - - - - a #GstCaps - - - - a function to call for each field - - - - private data - - - - - - Appends the structures contained in @caps2 to @caps1 if they are not yet -expressed by @caps1. The structures in @caps2 are not copied -- they are -transferred to a writable copy of @caps1, and then @caps2 is freed. -If either caps is ANY, the resulting caps will be ANY. - - - the merged caps. - - - - - the #GstCaps that will take the new entries - - - - the #GstCaps to merge in - - - - - - Appends @structure to @caps if its not already expressed by @caps. - - - the merged caps. - - - - - the #GstCaps to merge into - - - - the #GstStructure to merge - - - - - - Appends @structure with @features to @caps if its not already expressed by @caps. - - - the merged caps. - - - - - the #GstCaps to merge into - - - - the #GstStructure to merge - - - - the #GstCapsFeatures to merge - - - - - - Returns a #GstCaps that represents the same set of formats as -@caps, but contains no lists. Each list is expanded into separate -@GstStructures. - -This function takes ownership of @caps and will call gst_caps_make_writable() -on it so you must not use @caps afterwards unless you keep an additional -reference to it with gst_caps_ref(). - - - the normalized #GstCaps - - - - - a #GstCaps to normalize - - - - - - Add a reference to a #GstCaps object. - -From this point on, until the caller calls gst_caps_unref() or -gst_caps_make_writable(), it is guaranteed that the caps object will not -change. This means its structures won't change, etc. To use a #GstCaps -object, you must always have a refcount on it -- either the one made -implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with -this function. - - - the same #GstCaps object. - - - - - the #GstCaps to reference - - - - - - removes the structure with the given index from the list of structures -contained in @caps. - - - - - - - the #GstCaps to remove from - - - - Index of the structure to remove - - - - - - Sets the #GstCapsFeatures @features for the structure at @index. - - - - - - - a #GstCaps - - - - the index of the structure - - - - the #GstCapsFeatures to set - - - - - - Sets the #GstCapsFeatures @features for all the structures of @caps. - - - - - - - a #GstCaps - - - - the #GstCapsFeatures to set - - - - - - Sets fields in a #GstCaps. The arguments must be passed in the same -manner as gst_structure_set(), and be %NULL-terminated. - - - - - - - the #GstCaps to set - - - - first field to set - - - - additional parameters - - - - - - Sets fields in a #GstCaps. The arguments must be passed in the same -manner as gst_structure_set(), and be %NULL-terminated. - - - - - - - the #GstCaps to set - - - - first field to set - - - - additional parameters - - - - - - Sets the given @field on all structures of @caps to the given @value. -This is a convenience function for calling gst_structure_set_value() on -all structures of @caps. - - - - - - - a writable caps - - - - name of the field to set - - - - value to set the field to - - - - - - Converts the given @caps into a representation that represents the -same set of formats, but in a simpler form. Component structures that are -identical are merged. Component structures that have values that can be -merged are also merged. - -This function takes ownership of @caps and will call gst_caps_make_writable() -on it if necessary, so you must not use @caps afterwards unless you keep an -additional reference to it with gst_caps_ref(). - -This method does not preserve the original order of @caps. - - - The simplified caps. - - - - - a #GstCaps to simplify - - - - - - Retrieves the structure with the given index from the list of structures -contained in @caps. The caller becomes the owner of the returned structure. - - - a pointer to the #GstStructure - corresponding to @index. - - - - - the #GstCaps to retrieve from - - - - Index of the structure to retrieve - - - - - - Subtracts the @subtrahend from the @minuend. -> This function does not work reliably if optional properties for caps -> are included on one caps and omitted on the other. - - - the resulting caps - - - - - #GstCaps to subtract from - - - - #GstCaps to subtract - - - - - - Converts @caps to a string representation. This string representation -can be converted back to a #GstCaps by gst_caps_from_string(). - -For debugging purposes its easier to do something like this: -|[<!-- language="C" --> -GST_LOG ("caps are %" GST_PTR_FORMAT, caps); -]| -This prints the caps in human readable form. - -The current implementation of serialization will lead to unexpected results -when there are nested #GstCaps / #GstStructure deeper than one level. - - - a newly allocated string representing @caps. - - - - - a #GstCaps - - - - - - Discard all but the first structure from @caps. Useful when -fixating. - -This function takes ownership of @caps and will call gst_caps_make_writable() -on it if necessary, so you must not use @caps afterwards unless you keep an -additional reference to it with gst_caps_ref(). - -Note that it is not guaranteed that the returned caps have exactly one -structure. If @caps is any or empty caps then then returned caps will be -the same and contain no structure at all. - - - truncated caps - - - - - the #GstCaps to truncate - - - - - - Unref a #GstCaps and and free all its structures and the -structures' values when the refcount reaches 0. - - - - - - - a #GstCaps. - - - - - - Converts @caps from a string representation. - -The current implementation of serialization will lead to unexpected results -when there are nested #GstCaps / #GstStructure deeper than one level. - - - a newly allocated #GstCaps - - - - - a string to convert to #GstCaps - - - - - - Modifies a pointer to a #GstCaps to point to a different #GstCaps. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -caps is unreffed, the new is reffed). - -Either @new_caps or the #GstCaps pointed to by @old_caps may be %NULL. - - - %TRUE if @new_caps was different from @old_caps - - - - - pointer to a pointer - to a #GstCaps to be replaced. - - - - pointer to a #GstCaps that will - replace the caps pointed to by @old_caps. - - - - - - Modifies a pointer to a #GstCaps to point to a different #GstCaps. This -function is similar to gst_caps_replace() except that it takes ownership -of @new_caps. - - - %TRUE if @new_caps was different from @old_caps - - - - - pointer to a pointer to a #GstCaps to be - replaced. - - - - pointer to a #GstCaps that will - replace the caps pointed to by @old_caps. - - - - - - - #GstCapsFeatures can optionally be set on a #GstCaps to add requirements -for additional features for a specific #GstStructure. Caps structures with -the same name but with a non-equal set of caps features are not compatible. -If a pad supports multiple sets of features it has to add multiple equal -structures with different feature sets to the caps. - -Empty #GstCapsFeatures are equivalent with the #GstCapsFeatures that only -contain #GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY. ANY #GstCapsFeatures as -created by gst_caps_features_new_any() are equal to any other #GstCapsFeatures -and can be used to specify that any #GstCapsFeatures would be supported, e.g. -for elements that don't touch buffer memory. #GstCaps with ANY #GstCapsFeatures -are considered non-fixed and during negotiation some #GstCapsFeatures have -to be selected. - -Examples for caps features would be the requirement of a specific #GstMemory -types or the requirement of having a specific #GstMeta on the buffer. Features -are given as a string of the format "memory:GstMemoryTypeName" or -"meta:GstMetaAPIName". - - - Creates a new #GstCapsFeatures with the given features. -The last argument must be %NULL. - -Free-function: gst_caps_features_free - - - a new, empty #GstCapsFeatures - - - - - name of first feature to set - - - - additional features - - - - - - Creates a new, ANY #GstCapsFeatures. This will be equal -to any other #GstCapsFeatures but caps with these are -unfixed. - -Free-function: gst_caps_features_free - - - a new, ANY #GstCapsFeatures - - - - - Creates a new, empty #GstCapsFeatures. - -Free-function: gst_caps_features_free - - - a new, empty #GstCapsFeatures - - - - - Creates a new #GstCapsFeatures with the given features. -The last argument must be 0. - -Free-function: gst_caps_features_free - - - a new, empty #GstCapsFeatures - - - - - name of first feature to set - - - - additional features - - - - - - Creates a new #GstCapsFeatures with the given features. - -Free-function: gst_caps_features_free - - - a new, empty #GstCapsFeatures - - - - - name of first feature to set - - - - variable argument list - - - - - - Creates a new #GstCapsFeatures with the given features. - -Free-function: gst_caps_features_free - - - a new, empty #GstCapsFeatures - - - - - name of first feature to set - - - - variable argument list - - - - - - Adds @feature to @features. - - - - - - - a #GstCapsFeatures. - - - - a feature. - - - - - - Adds @feature to @features. - - - - - - - a #GstCapsFeatures. - - - - a feature. - - - - - - Check if @features contains @feature. - - - %TRUE if @features contains @feature. - - - - - a #GstCapsFeatures. - - - - a feature - - - - - - Check if @features contains @feature. - - - %TRUE if @features contains @feature. - - - - - a #GstCapsFeatures. - - - - a feature - - - - - - Duplicates a #GstCapsFeatures and all its values. - -Free-function: gst_caps_features_free - - - a new #GstCapsFeatures. - - - - - a #GstCapsFeatures to duplicate - - - - - - Frees a #GstCapsFeatures and all its values. The caps features must not -have a parent when this function is called. - - - - - - - the #GstCapsFeatures to free - - - - - - Returns the @i-th feature of @features. - - - The @i-th feature of @features. - - - - - a #GstCapsFeatures. - - - - index of the feature - - - - - - Returns the @i-th feature of @features. - - - The @i-th feature of @features. - - - - - a #GstCapsFeatures. - - - - index of the feature - - - - - - Returns the number of features in @features. - - - The number of features in @features. - - - - - a #GstCapsFeatures. - - - - - - Check if @features is %GST_CAPS_FEATURES_ANY. - - - %TRUE if @features is %GST_CAPS_FEATURES_ANY. - - - - - a #GstCapsFeatures. - - - - - - Check if @features1 and @features2 are equal. - - - %TRUE if @features1 and @features2 are equal. - - - - - a #GstCapsFeatures. - - - - a #GstCapsFeatures. - - - - - - Removes @feature from @features. - - - - - - - a #GstCapsFeatures. - - - - a feature. - - - - - - Removes @feature from @features. - - - - - - - a #GstCapsFeatures. - - - - a feature. - - - - - - Sets the parent_refcount field of #GstCapsFeatures. This field is used to -determine whether a caps features is mutable or not. This function should only be -called by code implementing parent objects of #GstCapsFeatures, as described in -the MT Refcounting section of the design documents. - - - %TRUE if the parent refcount could be set. - - - - - a #GstCapsFeatures - - - - a pointer to the parent's refcount - - - - - - Converts @features to a human-readable string representation. - -For debugging purposes its easier to do something like this: -|[<!-- language="C" --> -GST_LOG ("features is %" GST_PTR_FORMAT, features); -]| -This prints the features in human readable form. - -Free-function: g_free - - - a pointer to string allocated by g_malloc(). - g_free() after usage. - - - - - a #GstCapsFeatures - - - - - - Creates a #GstCapsFeatures from a string representation. - -Free-function: gst_caps_features_free - - - a new #GstCapsFeatures or - %NULL when the string could not be parsed. Free with - gst_caps_features_free() after use. - - - - - a string representation of a #GstCapsFeatures. - - - - - - - A function that will be called in gst_caps_filter_and_map_in_place(). -The function may modify @features and @structure, and both will be -removed from the caps if %FALSE is returned. - - - %TRUE if the features and structure should be preserved, -%FALSE if it should be removed. - - - - - the #GstCapsFeatures - - - - the #GstStructure - - - - user data - - - - - - Extra flags for a caps. - - Caps has no specific content, but can contain - anything. - - - - A function that will be called in gst_caps_foreach(). The function may -not modify @features or @structure. - - - %TRUE if the foreach operation should continue, %FALSE if -the foreach operation should stop with %FALSE. - - - - - the #GstCapsFeatures - - - - the #GstStructure - - - - user data - - - - - - Modes of caps intersection - -@GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps -by iterating on the caps' structures as the following matrix shows: -|[ - caps1 - +------------- - | 1 2 4 7 -caps2 | 3 5 8 10 - | 6 9 11 12 -]| -Used when there is no explicit precedence of one caps over the other. e.g. -tee's sink pad getcaps function, it will probe its src pad peers' for their -caps and intersect them with this mode. - -@GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve -another element's caps priority order when intersecting with its own caps. -Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result -would be [A, B], maintaining the first caps priority on the intersection. - - Zig-zags over both caps. - - - Keeps the first caps order. - - - - A function that will be called in gst_caps_map_in_place(). The function -may modify @features and @structure. - - - %TRUE if the map operation should continue, %FALSE if -the map operation should stop with %FALSE. - - - - - the #GstCapsFeatures - - - - the #GstStructure - - - - user data - - - - - - This interface abstracts handling of property sets for elements with -children. Imagine elements such as mixers or polyphonic generators. They all -have multiple #GstPad or some kind of voice objects. Another use case are -container elements like #GstBin. -The element implementing the interface acts as a parent for those child -objects. - -By implementing this interface the child properties can be accessed from the -parent element by using gst_child_proxy_get() and gst_child_proxy_set(). - -Property names are written as "child-name::property-name". The whole naming -scheme is recursive. Thus "child1::child2::property" is valid too, if -"child1" and "child2" implement the #GstChildProxy interface. - - - Emits the "child-added" signal. - - - - - - - the parent object - - - - the newly added child - - - - the name of the new child - - - - - - Emits the "child-removed" signal. - - - - - - - the parent object - - - - the removed child - - - - the name of the old child - - - - - - Fetches a child by its number. - - - the child object or %NULL if - not found (index too high). Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's position in the child list - - - - - - Looks up a child element by the given name. - -This virtual method has a default implementation that uses #GstObject -together with gst_object_get_name(). If the interface is to be used with -#GObjects, this methods needs to be overridden. - - - the child object or %NULL if - not found. Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's name - - - - - - Gets the number of child objects this parent contains. - - - the number of child objects - -MT safe. - - - - - the parent object - - - - - - Emits the "child-added" signal. - - - - - - - the parent object - - - - the newly added child - - - - the name of the new child - - - - - - Emits the "child-removed" signal. - - - - - - - the parent object - - - - the removed child - - - - the name of the old child - - - - - - Gets properties of the parent object and its children. - - - - - - - the parent object - - - - name of the first property to get - - - - return location for the first property, followed optionally by more name/return location pairs, followed by %NULL - - - - - - Fetches a child by its number. - - - the child object or %NULL if - not found (index too high). Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's position in the child list - - - - - - Looks up a child element by the given name. - -This virtual method has a default implementation that uses #GstObject -together with gst_object_get_name(). If the interface is to be used with -#GObjects, this methods needs to be overridden. - - - the child object or %NULL if - not found. Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's name - - - - - - Gets the number of child objects this parent contains. - - - the number of child objects - -MT safe. - - - - - the parent object - - - - - - Gets a single property using the GstChildProxy mechanism. -You are responsible for freeing it by calling g_value_unset() - - - - - - - object to query - - - - name of the property - - - - a #GValue that should take the result. - - - - - - Gets properties of the parent object and its children. - - - - - - - the object to query - - - - name of the first property to get - - - - return location for the first property, followed optionally by more name/return location pairs, followed by %NULL - - - - - - Looks up which object and #GParamSpec would be effected by the given @name. - -MT safe. - - - %TRUE if @target and @pspec could be found. %FALSE otherwise. In that -case the values for @pspec and @target are not modified. Unref @target after -usage. For plain GObjects @target is the same as @object. - - - - - child proxy object to lookup the property in - - - - name of the property to look up - - - - pointer to a #GObject that - takes the real object to set property on - - - - pointer to take the #GParamSpec - describing the property - - - - - - Sets properties of the parent object and its children. - - - - - - - the parent object - - - - name of the first property to set - - - - value for the first property, followed optionally by more name/value pairs, followed by %NULL - - - - - - Sets a single property using the GstChildProxy mechanism. - - - - - - - the parent object - - - - name of the property to set - - - - new #GValue for the property - - - - - - Sets properties of the parent object and its children. - - - - - - - the parent object - - - - name of the first property to set - - - - value for the first property, followed optionally by more name/value pairs, followed by %NULL - - - - - - Will be emitted after the @object was added to the @child_proxy. - - - - - - the #GObject that was added - - - - the name of the new child - - - - - - Will be emitted after the @object was removed from the @child_proxy. - - - - - - the #GObject that was removed - - - - the name of the old child - - - - - - - #GstChildProxy interface. - - - parent interface type. - - - - - - - the child object or %NULL if - not found. Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's name - - - - - - - - - - the child object or %NULL if - not found (index too high). Unref after usage. - -MT safe. - - - - - the parent object to get the child from - - - - the child's position in the child list - - - - - - - - - - the number of child objects - -MT safe. - - - - - the parent object - - - - - - - - - - - - - - the parent object - - - - the newly added child - - - - the name of the new child - - - - - - - - - - - - - - the parent object - - - - the removed child - - - - the name of the old child - - - - - - - - - - - - - GStreamer uses a global clock to synchronize the plugins in a pipeline. -Different clock implementations are possible by implementing this abstract -base class or, more conveniently, by subclassing #GstSystemClock. - -The #GstClock returns a monotonically increasing time with the method -gst_clock_get_time(). Its accuracy and base time depend on the specific -clock implementation but time is always expressed in nanoseconds. Since the -baseline of the clock is undefined, the clock time returned is not -meaningful in itself, what matters are the deltas between two clock times. -The time returned by a clock is called the absolute time. - -The pipeline uses the clock to calculate the running time. Usually all -renderers synchronize to the global clock using the buffer timestamps, the -newsegment events and the element's base time, see #GstPipeline. - -A clock implementation can support periodic and single shot clock -notifications both synchronous and asynchronous. - -One first needs to create a #GstClockID for the periodic or single shot -notification using gst_clock_new_single_shot_id() or -gst_clock_new_periodic_id(). - -To perform a blocking wait for the specific time of the #GstClockID use the -gst_clock_id_wait(). To receive a callback when the specific time is reached -in the clock use gst_clock_id_wait_async(). Both these calls can be -interrupted with the gst_clock_id_unschedule() call. If the blocking wait is -unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned. - -Periodic callbacks scheduled async will be repeatedly called automatically -until it is unscheduled. To schedule a sync periodic callback, -gst_clock_id_wait() should be called repeatedly. - -The async callbacks can happen from any thread, either provided by the core -or from a streaming thread. The application should be prepared for this. - -A #GstClockID that has been unscheduled cannot be used again for any wait -operation, a new #GstClockID should be created and the old unscheduled one -should be destroyed with gst_clock_id_unref(). - -It is possible to perform a blocking wait on the same #GstClockID from -multiple threads. However, registering the same #GstClockID for multiple -async notifications is not possible, the callback will only be called for -the thread registering the entry last. - -None of the wait operations unref the #GstClockID, the owner is responsible -for unreffing the ids itself. This holds for both periodic and single shot -notifications. The reason being that the owner of the #GstClockID has to -keep a handle to the #GstClockID to unblock the wait on FLUSHING events or -state changes and if the entry would be unreffed automatically, the handle -might become invalid without any notification. - -These clock operations do not operate on the running time, so the callbacks -will also occur when not in PLAYING state as if the clock just keeps on -running. Some clocks however do not progress when the element that provided -the clock is not PLAYING. - -When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be -slaved to another #GstClock with the gst_clock_set_master(). The clock will -then automatically be synchronized to this master clock by repeatedly -sampling the master clock and the slave clock and recalibrating the slave -clock with gst_clock_set_calibration(). This feature is mostly useful for -plugins that have an internal clock but must operate with another clock -selected by the #GstPipeline. They can track the offset and rate difference -of their internal clock relative to the master clock by using the -gst_clock_get_calibration() function. - -The master/slave synchronisation can be tuned with the #GstClock:timeout, -#GstClock:window-size and #GstClock:window-threshold properties. -The #GstClock:timeout property defines the interval to sample the master -clock and run the calibration functions. #GstClock:window-size defines the -number of samples to use when calibrating and #GstClock:window-threshold -defines the minimum number of samples before the calibration is performed. - - - Compares the two #GstClockID instances. This function can be used -as a GCompareFunc when sorting ids. - - - negative value if a < b; zero if a = b; positive value if a > b - -MT safe. - - - - - A #GstClockID - - - - A #GstClockID to compare with - - - - - - This function returns the underlying clock. - - - a #GstClock or %NULL when the - underlying clock has been freed. Unref after usage. - -MT safe. - - - - - a #GstClockID - - - - - - Get the time of the clock ID - - - the time of the given clock id. - -MT safe. - - - - - The #GstClockID to query - - - - - - Increase the refcount of given @id. - - - The same #GstClockID with increased refcount. - -MT safe. - - - - - The #GstClockID to ref - - - - - - Unref given @id. When the refcount reaches 0 the -#GstClockID will be freed. - -MT safe. - - - - - - - The #GstClockID to unref - - - - - - Cancel an outstanding request with @id. This can either -be an outstanding async notification or a pending sync notification. -After this call, @id cannot be used anymore to receive sync or -async notifications, you need to create a new #GstClockID. - -MT safe. - - - - - - - The id to unschedule - - - - - - This function returns whether @id uses @clock as the underlying clock. -@clock can be NULL, in which case the return value indicates whether -the underlying clock has been freed. If this is the case, the @id is -no longer usable and should be freed. - - - whether the clock @id uses the same underlying #GstClock @clock. - -MT safe. - - - - - a #GstClockID to check - - - - a #GstClock to compare against - - - - - - Perform a blocking wait on @id. -@id should have been created with gst_clock_new_single_shot_id() -or gst_clock_new_periodic_id() and should not have been unscheduled -with a call to gst_clock_id_unschedule(). - -If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK -or #GST_CLOCK_EARLY, it will contain the difference -against the clock and the time of @id when this method was -called. -Positive values indicate how late @id was relative to the clock -(in which case this function will return #GST_CLOCK_EARLY). -Negative values indicate how much time was spent waiting on the clock -before this function returned. - - - the result of the blocking wait. #GST_CLOCK_EARLY will be returned -if the current clock time is past the time of @id, #GST_CLOCK_OK if -@id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was -unscheduled with gst_clock_id_unschedule(). - -MT safe. - - - - - The #GstClockID to wait on - - - - a pointer that will contain the jitter, - can be %NULL. - - - - - - Register a callback on the given #GstClockID @id with the given -function and user_data. When passing a #GstClockID with an invalid -time to this function, the callback will be called immediately -with a time set to GST_CLOCK_TIME_NONE. The callback will -be called when the time of @id has been reached. - -The callback @func can be invoked from any thread, either provided by the -core or from a streaming thread. The application should be prepared for this. - - - the result of the non blocking wait. - -MT safe. - - - - - a #GstClockID to wait on - - - - The callback function - - - - User data passed in the callback - - - - #GDestroyNotify for user_data - - - - - - - - - - - - - - - - - - - - - - - Gets the current internal time of the given clock. The time is returned -unadjusted for the offset and the rate. - - - the internal time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - - - - - a #GstClock to query - - - - - - Get the accuracy of the clock. The accuracy of the clock is the granularity -of the values returned by gst_clock_get_time(). - - - the resolution of the clock in units of #GstClockTime. - -MT safe. - - - - - a #GstClock - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The time @master of the master clock and the time @slave of the slave -clock are added to the list of observations. If enough observations -are available, a linear regression algorithm is run on the -observations and @clock is recalibrated. - -If this functions returns %TRUE, @r_squared will contain the -correlation coefficient of the interpolation. A value of 1.0 -means a perfect regression was performed. This value can -be used to control the sampling frequency of the master and slave -clocks. - - - %TRUE if enough observations were added to run the -regression algorithm. - -MT safe. - - - - - a #GstClock - - - - a time on the slave - - - - a time on the master - - - - a pointer to hold the result - - - - - - Add a clock observation to the internal slaving algorithm the same as -gst_clock_add_observation(), and return the result of the master clock -estimation, without updating the internal calibration. - -The caller can then take the results and call gst_clock_set_calibration() -with the values, or some modified version of them. - - - - - - - a #GstClock - - - - a time on the slave - - - - a time on the master - - - - a pointer to hold the result - - - - a location to store the internal time - - - - a location to store the external time - - - - a location to store the rate numerator - - - - a location to store the rate denominator - - - - - - Converts the given @internal clock time to the external time, adjusting for the -rate and reference time set with gst_clock_set_calibration() and making sure -that the returned time is increasing. This function should be called with the -clock's OBJECT_LOCK held and is mainly used by clock subclasses. - -This function is the reverse of gst_clock_unadjust_unlocked(). - - - the converted time of the clock. - - - - - a #GstClock to use - - - - a clock time - - - - - - Converts the given @internal_target clock time to the external time, -using the passed calibration parameters. This function performs the -same calculation as gst_clock_adjust_unlocked() when called using the -current calibration parameters, but doesn't ensure a monotonically -increasing result as gst_clock_adjust_unlocked() does. - -Note: The @clock parameter is unused and can be NULL - - - the converted time of the clock. - - - - - a #GstClock to use - - - - a clock time - - - - a reference internal time - - - - a reference external time - - - - the numerator of the rate of the clock relative to its - internal time - - - - the denominator of the rate of the clock - - - - - - Gets the internal rate and reference time of @clock. See -gst_clock_set_calibration() for more information. - -@internal, @external, @rate_num, and @rate_denom can be left %NULL if the -caller is not interested in the values. - -MT safe. - - - - - - - a #GstClock - - - - a location to store the internal time - - - - a location to store the external time - - - - a location to store the rate numerator - - - - a location to store the rate denominator - - - - - - Gets the current internal time of the given clock. The time is returned -unadjusted for the offset and the rate. - - - the internal time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - - - - - a #GstClock to query - - - - - - Get the master clock that @clock is slaved to or %NULL when the clock is -not slaved to any master clock. - - - a master #GstClock or %NULL - when this clock is not slaved to a master clock. Unref after - usage. - -MT safe. - - - - - a #GstClock - - - - - - Get the accuracy of the clock. The accuracy of the clock is the granularity -of the values returned by gst_clock_get_time(). - - - the resolution of the clock in units of #GstClockTime. - -MT safe. - - - - - a #GstClock - - - - - - Gets the current time of the given clock. The time is always -monotonically increasing and adjusted according to the current -offset and rate. - - - the time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - - - - - a #GstClock to query - - - - - - Get the amount of time that master and slave clocks are sampled. - - - the interval between samples. - - - - - a #GstClock - - - - - - Checks if the clock is currently synced. - -This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock. - - - %TRUE if the clock is currently synced - - - - - a GstClock - - - - - - Get an ID from @clock to trigger a periodic notification. -The periodic notifications will start at time @start_time and -will then be fired with the given @interval. @id should be unreffed -after usage. - -Free-function: gst_clock_id_unref - - - a #GstClockID that can be used to request the - time notification. - -MT safe. - - - - - The #GstClockID to get a periodic notification id from - - - - the requested start time - - - - the requested interval - - - - - - Get a #GstClockID from @clock to trigger a single shot -notification at the requested time. The single shot id should be -unreffed after usage. - -Free-function: gst_clock_id_unref - - - a #GstClockID that can be used to request the - time notification. - -MT safe. - - - - - The #GstClockID to get a single shot notification from - - - - the requested time - - - - - - Reinitializes the provided periodic @id to the provided start time and -interval. Does not modify the reference count. - - - %TRUE if the GstClockID could be reinitialized to the provided -@time, else %FALSE. - - - - - a #GstClock - - - - a #GstClockID - - - - the requested start time - - - - the requested interval - - - - - - Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of -the clock. Values bigger than 1/1 make the clock go faster. - -@internal and @external are calibration parameters that arrange that -gst_clock_get_time() should have been @external at internal time @internal. -This internal time should not be in the future; that is, it should be less -than the value of gst_clock_get_internal_time() when this function is called. - -Subsequent calls to gst_clock_get_time() will return clock times computed as -follows: - -|[ - time = (internal_time - internal) * rate_num / rate_denom + external -]| - -This formula is implemented in gst_clock_adjust_unlocked(). Of course, it -tries to do the integer arithmetic as precisely as possible. - -Note that gst_clock_get_time() always returns increasing values so when you -move the clock backwards, gst_clock_get_time() will report the previous value -until the clock catches up. - -MT safe. - - - - - - - a #GstClock to calibrate - - - - a reference internal time - - - - a reference external time - - - - the numerator of the rate of the clock relative to its - internal time - - - - the denominator of the rate of the clock - - - - - - Set @master as the master clock for @clock. @clock will be automatically -calibrated so that gst_clock_get_time() reports the same time as the -master clock. - -A clock provider that slaves its clock to a master can get the current -calibration values with gst_clock_get_calibration(). - -@master can be %NULL in which case @clock will not be slaved anymore. It will -however keep reporting its time adjusted with the last configured rate -and time offsets. - - - %TRUE if the clock is capable of being slaved to a master clock. -Trying to set a master on a clock without the -#GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE. - -MT safe. - - - - - a #GstClock - - - - a master #GstClock - - - - - - Set the accuracy of the clock. Some clocks have the possibility to operate -with different accuracy at the expense of more resource usage. There is -normally no need to change the default resolution of a clock. The resolution -of a clock can only be changed if the clock has the -#GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set. - - - the new resolution of the clock. - - - - - a #GstClock - - - - The resolution to set - - - - - - Sets @clock to synced and emits the GstClock::synced signal, and wakes up any -thread waiting in gst_clock_wait_for_sync(). - -This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC -is set on the clock, and is intended to be called by subclasses only. - - - - - - - a GstClock - - - - if the clock is synced - - - - - - Set the amount of time, in nanoseconds, to sample master and slave -clocks - - - - - - - a #GstClock - - - - a timeout - - - - - - Reinitializes the provided single shot @id to the provided time. Does not -modify the reference count. - - - %TRUE if the GstClockID could be reinitialized to the provided -@time, else %FALSE. - - - - - a #GstClock - - - - a #GstClockID - - - - The requested time. - - - - - - Converts the given @external clock time to the internal time of @clock, -using the rate and reference time set with gst_clock_set_calibration(). -This function should be called with the clock's OBJECT_LOCK held and -is mainly used by clock subclasses. - -This function is the reverse of gst_clock_adjust_unlocked(). - - - the internal time of the clock corresponding to @external. - - - - - a #GstClock to use - - - - an external clock time - - - - - - Converts the given @external_target clock time to the internal time, -using the passed calibration parameters. This function performs the -same calculation as gst_clock_unadjust_unlocked() when called using the -current calibration parameters. - -Note: The @clock parameter is unused and can be NULL - - - the converted time of the clock. - - - - - a #GstClock to use - - - - a clock time - - - - a reference internal time - - - - a reference external time - - - - the numerator of the rate of the clock relative to its - internal time - - - - the denominator of the rate of the clock - - - - - - Waits until @clock is synced for reporting the current time. If @timeout -is %GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out -after @timeout nanoseconds. - -For asynchronous waiting, the GstClock::synced signal can be used. - -This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC -is not set on the clock, or if the clock is already synced. - - - %TRUE if waiting was successful, or %FALSE on timeout - - - - - a GstClock - - - - timeout for waiting or %GST_CLOCK_TIME_NONE - - - - - - - - - - - - - - - - - - - - - - - - - - Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once -the clock is synchronized, or when it completely lost synchronization. -This signal will not be emitted on clocks without the flag. - -This signal will be emitted from an arbitrary thread, most likely not -the application's main thread. - - - - - - if the clock is synced now - - - - - - - The function prototype of the callback. - - - %TRUE or %FALSE (currently unused) - - - - - The clock that triggered the callback - - - - The time it was triggered - - - - The #GstClockID that expired - - - - user data passed in the gst_clock_id_wait_async() function - - - - - - GStreamer clock class. Override the vmethods to implement the clock -functionality. - - - the parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - the resolution of the clock in units of #GstClockTime. - -MT safe. - - - - - a #GstClock - - - - - - - - - - the internal time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - - - - - a #GstClock to query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - All pending timeouts or periodic notifies are converted into -an entry. -Note that GstClockEntry should be treated as an opaque structure. It must -not be extended or allocated using a custom allocator. - - - reference counter (read-only) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of the clock entry - - a single shot timeout - - - a periodic timeout request - - - - The capabilities of this clock - - clock can do a single sync timeout request - - - clock can do a single async timeout request - - - clock can do sync periodic timeout requests - - - clock can do async periodic timeout callbacks - - - clock's resolution can be changed - - - clock can be slaved to a master clock - - - clock needs to be synced before it can be used - (Since: 1.6) - - - subclasses can add additional flags starting from this flag - - - - - - - The return value of a clock operation. - - The operation succeeded. - - - The operation was scheduled too late. - - - The clockID was unscheduled - - - The ClockID is busy - - - A bad time was provided to a function. - - - An error occurred - - - Operation is not supported - - - The ClockID is done waiting - - - - The different kind of clocks. - - time since Epoch - - - monotonic time since some unspecified starting - point - - - some other time source is used (Since: 1.0.5) - - - time since Epoch, but using International Atomic Time - as reference (Since: 1.18) - - - - #GstContext is a container object used to store contexts like a device -context, a display server connection and similar concepts that should -be shared between multiple elements. - -Applications can set a context on a complete pipeline by using -gst_element_set_context(), which will then be propagated to all -child elements. Elements can handle these in #GstElementClass.set_context() -and merge them with the context information they already have. - -When an element needs a context it will do the following actions in this -order until one step succeeds: -1. Check if the element already has a context -2. Query downstream with GST_QUERY_CONTEXT for the context -3. Query upstream with GST_QUERY_CONTEXT for the context -4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required - context types and afterwards check if a usable context was set now -5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message - on the bus. - -Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously -known context on the element that asks for it if possible. Otherwise the -application should provide one if it can. - -#GstContext<!-- -->s can be persistent. -A persistent #GstContext is kept in elements when they reach -%GST_STATE_NULL, non-persistent ones will be removed. -Also, a non-persistent context won't override a previous persistent -context set to an element. - - - Create a new context. - - - The new context. - - - - - Context type - - - - Persistent context - - - - - - Get the type of @context. - - - The type of the context. - - - - - The #GstContext. - - - - - - Access the structure of the context. - - - The structure of the context. The structure is -still owned by the context, which means that you should not modify it, -free it and that the pointer becomes invalid when you free the context. - - - - - The #GstContext. - - - - - - Checks if @context has @context_type. - - - %TRUE if @context has @context_type. - - - - - The #GstContext. - - - - Context type to check. - - - - - - Check if @context is persistent. - - - %TRUE if the context is persistent. - - - - - The #GstContext. - - - - - - Get a writable version of the structure. - - - The structure of the context. The structure is still -owned by the context, which means that you should not free it and -that the pointer becomes invalid when you free the context. -This function checks if @context is writable. - - - - - The #GstContext. - - - - - - - A base class for value mapping objects that attaches control sources to gobject -properties. Such an object is taking one or more #GstControlSource instances, -combines them and maps the resulting value to the type and value range of the -bound property. - - - Gets a number of #GValues for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -#GValue. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - Gets the value for the given controlled property at the requested time. - - - the GValue of the property at the given time, -or %NULL if the property isn't controlled. - - - - - the control binding - - - - the time the control-change should be read from - - - - - - Gets a number of values for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -the same type as the objects property's type. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - -The values are unboxed and ready to be used. The similar function -gst_control_binding_get_g_value_array() returns the array as #GValues and is -more suitable for bindings. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - Sets the property of the @object, according to the #GstControlSources that -handle them and for the given timestamp. - -If this function fails, it is most likely the application developers fault. -Most probably the control sources are not setup correctly. - - - %TRUE if the controller value could be applied to the object -property, %FALSE otherwise - - - - - the control binding - - - - the object that has controlled properties - - - - the time that should be processed - - - - the last time this was called - - - - - - Gets a number of #GValues for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -#GValue. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - Gets the value for the given controlled property at the requested time. - - - the GValue of the property at the given time, -or %NULL if the property isn't controlled. - - - - - the control binding - - - - the time the control-change should be read from - - - - - - Gets a number of values for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -the same type as the objects property's type. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - -The values are unboxed and ready to be used. The similar function -gst_control_binding_get_g_value_array() returns the array as #GValues and is -more suitable for bindings. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - Check if the control binding is disabled. - - - %TRUE if the binding is inactive - - - - - the control binding - - - - - - This function is used to disable a control binding for some time, i.e. -gst_object_sync_values() will do nothing. - - - - - - - the control binding - - - - boolean that specifies whether to disable the controller -or not. - - - - - - Sets the property of the @object, according to the #GstControlSources that -handle them and for the given timestamp. - -If this function fails, it is most likely the application developers fault. -Most probably the control sources are not setup correctly. - - - %TRUE if the controller value could be applied to the object -property, %FALSE otherwise - - - - - the control binding - - - - the object that has controlled properties - - - - the time that should be processed - - - - the last time this was called - - - - - - - - - - - - - - - name of the property of this binding - - - - #GParamSpec for this property - - - - - - - - - - - - - - - - - - - - - - - - - The class structure of #GstControlBinding. - - - Parent class - - - - - - - %TRUE if the controller value could be applied to the object -property, %FALSE otherwise - - - - - the control binding - - - - the object that has controlled properties - - - - the time that should be processed - - - - the last time this was called - - - - - - - - - - the GValue of the property at the given time, -or %NULL if the property isn't controlled. - - - - - the control binding - - - - the time the control-change should be read from - - - - - - - - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - - - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the control binding - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - - - - - - - - - FIXME(2.0): remove, this is unused - - - - - - - - - - - - - - - - - - - - - The #GstControlSource is a base class for control value sources that could -be used to get timestamp-value pairs. A control source essentially is a -function over time. - -A #GstControlSource is used by first getting an instance of a specific -control-source, creating a binding for the control-source to the target property -of the element and then adding the binding to the element. The binding will -convert the data types and value range to fit to the bound property. - -For implementing a new #GstControlSource one has to implement -#GstControlSourceGetValue and #GstControlSourceGetValueArray functions. -These are then used by gst_control_source_get_value() and -gst_control_source_get_value_array() to get values for specific timestamps. - - - Gets the value for this #GstControlSource at a given timestamp. - - - %FALSE if the value couldn't be returned, %TRUE otherwise. - - - - - the #GstControlSource object - - - - the time for which the value should be returned - - - - the value - - - - - - Gets an array of values for for this #GstControlSource. Values that are -undefined contain NANs. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the #GstControlSource object - - - - the first timestamp - - - - the time steps - - - - the number of values to fetch - - - - array to put control-values in - - - - - - - - - - - Function for returning a value for a given timestamp - - - - Function for returning a values array for a given timestamp - - - - - - - - - - The class structure of #GstControlSource. - - - Parent class - - - - - - - - - - Function for returning a value for a given timestamp. - - - %TRUE if the value was successfully calculated. - - - - - the #GstControlSource instance - - - - timestamp for which a value should be calculated - - - - a value which will be set to the result. - - - - - - Function for returning an array of values for starting at a given timestamp. - - - %TRUE if the values were successfully calculated. - - - - - the #GstControlSource instance - - - - timestamp for which a value should be calculated - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - Core errors are errors inside the core GStreamer library. - - a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - - - do not use this except as a placeholder for -deciding where to go while developing code. - - - use this when you do not want to implement -this functionality yet. - - - used for state change errors. - - - used for pad-related errors. - - - used for thread-related errors. - - - used for negotiation-related errors. - - - used for event-related errors. - - - used for seek-related errors. - - - used for caps-related errors. - - - used for negotiation-related errors. - - - used if a plugin is missing. - - - used for clock related errors. - - - used if functionality has been disabled at - compile time. - - - the number of core error types. - - - - - - - - - - - - - - To aid debugging applications one can use this method to write out the whole -network of gstreamer elements that form the pipeline into an dot file. -This file can be processed with graphviz to get an image, like this: -|[ - dot -Tpng -oimage.png graph_lowlevel.dot -]| -There is also a utility called xdot which allows you to view the dot file -directly without converting it first. - -The macro is only active if the environment variable GST_DEBUG_DUMP_DOT_DIR -is set to a basepath (e.g. /tmp), and the GStreamer debugging subsystem is -enabled (i.e., no use of `./configure --disable-gst-debug') - - - - the top-level pipeline that should be analyzed - - - details to show in the graph, e.g. #GST_DEBUG_GRAPH_SHOW_ALL or - one or more other #GstDebugGraphDetails flags. - - - output base filename (e.g. "myplayer") - - - - - This works like GST_DEBUG_BIN_TO_DOT_FILE(), but adds the current timestamp -to the filename, so that it can be used to take multiple snapshots. - - - - the top-level pipeline that should be analyzed - - - details to show in the graph, e.g. #GST_DEBUG_GRAPH_SHOW_ALL or - one or more other #GstDebugGraphDetails flags. - - - output base filename (e.g. "myplayer") - - - - - Defines a GstDebugCategory variable. -This macro expands to nothing if debugging is disabled. - - - - the category - - - - - Declares a GstDebugCategory variable as extern. Use in header files. -This macro expands to nothing if debugging is disabled. - - - - the category - - - - - Looks up an existing #GstDebugCategory by its @name and sets @cat. If the -category is not found, but GST_CAT_DEFAULT is defined, that is assigned to -@cat. Otherwise @cat will be %NULL. - -|[<!-- language="C" --> -GST_DEBUG_CATEGORY_STATIC (gst_myplugin_debug); -#define GST_CAT_DEFAULT gst_myplugin_debug -GST_DEBUG_CATEGORY_STATIC (GST_CAT_PERFORMANCE); -... -GST_DEBUG_CATEGORY_INIT (gst_myplugin_debug, "myplugin", 0, "nice element"); -GST_DEBUG_CATEGORY_GET (GST_CAT_PERFORMANCE, "GST_PERFORMANCE"); -]| - - - - the category to initialize. - - - log category name - - - - - Initializes a new #GstDebugCategory with the given properties and set to -the default threshold. - -> This macro expands to nothing if debugging is disabled. -> -> When naming your category, please follow the following conventions to ensure -> that the pattern matching for categories works as expected. It is not -> earth-shattering if you don't follow these conventions, but it would be nice -> for everyone. -> -> If you define a category for a plugin or a feature of it, name the category -> like the feature. So if you wanted to write a "filesrc" element, you would -> name the category "filesrc". Use lowercase letters only. -> If you define more than one category for the same element, append an -> underscore and an identifier to your categories, like this: "filesrc_cache" -> -> If you create a library or an application using debugging categories, use a -> common prefix followed by an underscore for all your categories. GStreamer -> uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure -> to include uppercase letters. - - - - the category to initialize. - - - the name of the category. - - - the colors to use for a color representation or 0 for no color. - - - optional description of the category. - - - - - Defines a static GstDebugCategory variable. -This macro expands to nothing if debugging is disabled. - - - - the category - - - - - - - - - - - - - Register a pointer to a function with its name, so it can later be used by -GST_DEBUG_FUNCPTR_NAME(). - - - - pointer to the function to register - - - - - Retrieves the name of the function, if it was previously registered with -GST_DEBUG_FUNCPTR(). If not, it returns a description of the pointer. - -This macro returns a constant string which must not be modified or -freed by the caller. - - - - address of the function of which to look up the name - - - - - Evaluates to 2 strings, that describe the pad. Often used in debugging -statements. - - - - The pad to debug. - - - - - Register a pointer to a function with its name, so it can later be used by -GST_DEBUG_FUNCPTR_NAME(). - -Use this variant of #GST_DEBUG_FUNCPTR if you do not need to use @ptr. - - - - pointer to the function to register - - - - - Define a new mini-object type with the given name - - - - name of the new type in CamelCase - - - name of the new type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Struct to store date, time and timezone information altogether. -#GstDateTime is refcounted and immutable. - -Date information is handled using the proleptic Gregorian calendar. - -Provides basic creation functions and accessor functions to its fields. - - - Creates a new #GstDateTime using the date and times in the gregorian calendar -in the supplied timezone. - -@year should be from 1 to 9999, @month should be from 1 to 12, @day from -1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59. - -Note that @tzoffset is a float and was chosen so for being able to handle -some fractional timezones, while it still keeps the readability of -representing it in hours for most timezones. - -If value is -1 then all over value will be ignored. For example -if @month == -1, then #GstDateTime will created only for @year. If -@day == -1, then #GstDateTime will created for @year and @month and -so on. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - Offset from UTC in hours. - - - - the gregorian year - - - - the gregorian month - - - - the day of the gregorian month - - - - the hour of the day - - - - the minute of the hour - - - - the second of the minute - - - - - - Creates a new #GstDateTime from a #GDateTime object. - -Free-function: gst_date_time_unref - - - a newly created #GstDateTime, -or %NULL on error - - - - - the #GDateTime. The new #GstDateTime takes ownership. - - - - - - Tries to parse common variants of ISO-8601 datetime strings into a -#GstDateTime. Possible input formats are (for example): -2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, -2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, -2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, -22:46:43-0430, 22:46-0430, 22:46:30, 22:46 -If no date is provided, it is assumed to be "today" in the timezone -provided (if any), otherwise UTC. - -Free-function: gst_date_time_unref - - - a newly created #GstDateTime, -or %NULL on error - - - - - ISO 8601-formatted datetime string. - - - - - - Creates a new #GstDateTime using the time since Jan 1, 1970 specified by -@secs. The #GstDateTime is in the local timezone. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - seconds from the Unix epoch - - - - - - Creates a new #GstDateTime using the time since Jan 1, 1970 specified by -@usecs. The #GstDateTime is in the local timezone. - - - a newly created #GstDateTime - - - - - microseconds from the Unix epoch - - - - - - Creates a new #GstDateTime using the time since Jan 1, 1970 specified by -@secs. The #GstDateTime is in the UTC timezone. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - seconds from the Unix epoch - - - - - - Creates a new #GstDateTime using the time since Jan 1, 1970 specified by -@usecs. The #GstDateTime is in UTC. - - - a newly created #GstDateTime - - - - - microseconds from the Unix epoch - - - - - - Creates a new #GstDateTime using the date and times in the gregorian calendar -in the local timezone. - -@year should be from 1 to 9999, @month should be from 1 to 12, @day from -1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59. - -If @month is -1, then the #GstDateTime created will only contain @year, -and all other fields will be considered not set. - -If @day is -1, then the #GstDateTime created will only contain @year and -@month and all other fields will be considered not set. - -If @hour is -1, then the #GstDateTime created will only contain @year and -@month and @day, and the time fields will be considered not set. In this -case @minute and @seconds should also be -1. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - the gregorian year - - - - the gregorian month, or -1 - - - - the day of the gregorian month, or -1 - - - - the hour of the day, or -1 - - - - the minute of the hour, or -1 - - - - the second of the minute, or -1 - - - - - - Creates a new #GstDateTime representing the current date and time. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime which should - be freed with gst_date_time_unref(). - - - - - Creates a new #GstDateTime that represents the current instant at Universal -coordinated time. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime which should - be freed with gst_date_time_unref(). - - - - - Creates a new #GstDateTime using the date and times in the gregorian calendar -in the local timezone. - -@year should be from 1 to 9999. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - the gregorian year - - - - - - Creates a new #GstDateTime using the date and times in the gregorian calendar -in the local timezone. - -@year should be from 1 to 9999, @month should be from 1 to 12. - -If value is -1 then all over value will be ignored. For example -if @month == -1, then #GstDateTime will created only for @year. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - the gregorian year - - - - the gregorian month - - - - - - Creates a new #GstDateTime using the date and times in the gregorian calendar -in the local timezone. - -@year should be from 1 to 9999, @month should be from 1 to 12, @day from -1 to 31. - -If value is -1 then all over value will be ignored. For example -if @month == -1, then #GstDateTime will created only for @year. If -@day == -1, then #GstDateTime will created for @year and @month and -so on. - -Free-function: gst_date_time_unref - - - the newly created #GstDateTime - - - - - the gregorian year - - - - the gregorian month - - - - the day of the gregorian month - - - - - - Returns the day of the month of this #GstDateTime. -Call gst_date_time_has_day() before, to avoid warnings. - - - The day of this #GstDateTime - - - - - a #GstDateTime - - - - - - Retrieves the hour of the day represented by @datetime in the gregorian -calendar. The return is in the range of 0 to 23. -Call gst_date_time_has_time() before, to avoid warnings. - - - the hour of the day - - - - - a #GstDateTime - - - - - - Retrieves the fractional part of the seconds in microseconds represented by -@datetime in the gregorian calendar. - - - the microsecond of the second - - - - - a #GstDateTime - - - - - - Retrieves the minute of the hour represented by @datetime in the gregorian -calendar. -Call gst_date_time_has_time() before, to avoid warnings. - - - the minute of the hour - - - - - a #GstDateTime - - - - - - Returns the month of this #GstDateTime. January is 1, February is 2, etc.. -Call gst_date_time_has_month() before, to avoid warnings. - - - The month of this #GstDateTime - - - - - a #GstDateTime - - - - - - Retrieves the second of the minute represented by @datetime in the gregorian -calendar. -Call gst_date_time_has_time() before, to avoid warnings. - - - the second represented by @datetime - - - - - a #GstDateTime - - - - - - Retrieves the offset from UTC in hours that the timezone specified -by @datetime represents. Timezones ahead (to the east) of UTC have positive -values, timezones before (to the west) of UTC have negative values. -If @datetime represents UTC time, then the offset is zero. - - - the offset from UTC in hours - - - - - a #GstDateTime - - - - - - Returns the year of this #GstDateTime -Call gst_date_time_has_year() before, to avoid warnings. - - - The year of this #GstDateTime - - - - - a #GstDateTime - - - - - - - - %TRUE if @datetime<!-- -->'s day field is set, otherwise %FALSE - - - - - a #GstDateTime - - - - - - - - %TRUE if @datetime<!-- -->'s month field is set, otherwise %FALSE - - - - - a #GstDateTime - - - - - - - - %TRUE if @datetime<!-- -->'s second field is set, otherwise %FALSE - - - - - a #GstDateTime - - - - - - - - %TRUE if @datetime<!-- -->'s hour and minute fields are set, - otherwise %FALSE - - - - - a #GstDateTime - - - - - - - - %TRUE if @datetime<!-- -->'s year field is set (which should always - be the case), otherwise %FALSE - - - - - a #GstDateTime - - - - - - Atomically increments the reference count of @datetime by one. - - - the reference @datetime - - - - - a #GstDateTime - - - - - - Creates a new #GDateTime from a fully defined #GstDateTime object. - -Free-function: g_date_time_unref - - - a newly created #GDateTime, or -%NULL on error - - - - - GstDateTime. - - - - - - Create a minimal string compatible with ISO-8601. Possible output formats -are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, -2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100 - - - a newly allocated string formatted according - to ISO 8601 and only including the datetime fields that are - valid, or %NULL in case there was an error. The string should - be freed with g_free(). - - - - - GstDateTime. - - - - - - Atomically decrements the reference count of @datetime by one. When the -reference count reaches zero, the structure is freed. - - - - - - - a #GstDateTime - - - - - - - This is the struct that describes the categories. Once initialized with -#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore. - - - - - - - - - - - - - - - Removes and frees the category and all associated resources. - This function can easily cause memory corruption, don't use it. - - - - - - - #GstDebugCategory to free. - - - - - - Returns the color of a debug category used when printing output in this -category. - - - the color of the category. - - - - - a #GstDebugCategory to get the color of. - - - - - - Returns the description of a debug category. - - - the description of the category. - - - - - a #GstDebugCategory to get the description of. - - - - - - Returns the name of a debug category. - - - the name of the category. - - - - - a #GstDebugCategory to get name of. - - - - - - Returns the threshold of a #GstDebugCategory. - - - the #GstDebugLevel that is used as threshold. - - - - - a #GstDebugCategory to get threshold of. - - - - - - Resets the threshold of the category to the default level. Debug information -will only be output if the threshold is lower or equal to the level of the -debugging message. -Use this function to set the threshold back to where it was after using -gst_debug_category_set_threshold(). - - - - - - - a #GstDebugCategory to reset threshold of. - - - - - - Sets the threshold of the category to the given level. Debug information will -only be output if the threshold is lower or equal to the level of the -debugging message. -> Do not use this function in production code, because other functions may -> change the threshold of categories as side effect. It is however a nice -> function to use when debugging (even from gdb). - - - - - - - a #GstDebugCategory to set threshold of. - - - - the #GstDebugLevel threshold to set. - - - - - - - These are some terminal style flags you can use when creating your -debugging categories to make them stand out in debugging output. - - Use black as foreground color. - - - Use red as foreground color. - - - Use green as foreground color. - - - Use yellow as foreground color. - - - Use blue as foreground color. - - - Use magenta as foreground color. - - - Use cyan as foreground color. - - - Use white as foreground color. - - - Use black as background color. - - - Use red as background color. - - - Use green as background color. - - - Use yellow as background color. - - - Use blue as background color. - - - Use magenta as background color. - - - Use cyan as background color. - - - Use white as background color. - - - Make the output bold. - - - Underline the output. - - - - - Do not use colors in logs. - - - Paint logs in a platform-specific way. - - - Paint logs with UNIX terminal color codes - no matter what platform GStreamer is running on. - - - - - we define this to avoid a compiler warning regarding a cast from a function -pointer to a void pointer -(see https://bugzilla.gnome.org/show_bug.cgi?id=309253) - - - - - - - Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() -and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(). - - show caps-name on edges - - - show caps-details on edges - - - show modified parameters on - elements - - - show element states - - - show full element parameter values even - if they are very long - - - show all the typical details that one might want - - - show all details regardless of how large or - verbose they make the resulting output - - - - The level defines the importance of a debugging message. The more important a -message is, the greater the probability that the debugging system outputs it. - - No debugging level specified or desired. Used to deactivate - debugging output. - - - Error messages are to be used only when an error occurred - that stops the application from keeping working correctly. - An examples is gst_element_error, which outputs a message with this priority. - It does not mean that the application is terminating as with g_error. - - - Warning messages are to inform about abnormal behaviour - that could lead to problems or weird behaviour later on. An example of this - would be clocking issues ("your computer is pretty slow") or broken input - data ("Can't synchronize to stream.") - - - Fixme messages are messages that indicate that something - in the executed code path is not fully implemented or handled yet. Note - that this does not replace proper error handling in any way, the purpose - of this message is to make it easier to spot incomplete/unfinished pieces - of code when reading the debug log. - - - Informational messages should be used to keep the developer - updated about what is happening. - Examples where this should be used are when a typefind function has - successfully determined the type of the stream or when an mp3 plugin detects - the format to be used. ("This file has mono sound.") - - - Debugging messages should be used when something common - happens that is not the expected default behavior, or something that's - useful to know but doesn't happen all the time (ie. per loop iteration or - buffer processed or event handled). - An example would be notifications about state changes or receiving/sending - of events. - - - Log messages are messages that are very common but might be - useful to know. As a rule of thumb a pipeline that is running as expected - should never output anything else but LOG messages whilst processing data. - Use this log level to log recurring information in chain functions and - loop functions, for example. - - - Tracing-related messages. - Examples for this are referencing/dereferencing of objects. - - - memory dump messages are used to log (small) chunks of - data as memory dumps in the log. They will be displayed as hexdump with - ASCII characters. - - - The number of defined debugging levels. - - - Get the string representation of a debugging level - - - the name - - - - - the level to get the name for - - - - - - - - - Gets the string representation of a #GstDebugMessage. This function is used -in debug handlers to extract the message. - - - the string representation of a #GstDebugMessage. - - - - - a debug message - - - - - - - #GstDevice are objects representing a device, they contain -relevant metadata about the device, such as its class and the #GstCaps -representing the media types it can produce or handle. - -#GstDevice are created by #GstDeviceProvider objects which can be -aggregated by #GstDeviceMonitor objects. - - - Creates the element with all of the required parameters set to use -this device. - - - a new #GstElement configured to use -this device - - - - - a #GstDevice - - - - name of new element, or %NULL to automatically -create a unique name. - - - - - - Tries to reconfigure an existing element to use the device. If this -function fails, then one must destroy the element and create a new one -using gst_device_create_element(). - -Note: This should only be implemented for elements can change their -device in the PLAYING state. - - - %TRUE if the element could be reconfigured to use this device, -%FALSE otherwise. - - - - - a #GstDevice - - - - a #GstElement - - - - - - Creates the element with all of the required parameters set to use -this device. - - - a new #GstElement configured to use -this device - - - - - a #GstDevice - - - - name of new element, or %NULL to automatically -create a unique name. - - - - - - Getter for the #GstCaps that this device supports. - - - The #GstCaps supported by this device. Unref with -gst_caps_unref() when done. - - - - - a #GstDevice - - - - - - Gets the "class" of a device. This is a "/" separated list of -classes that represent this device. They are a subset of the -classes of the #GstDeviceProvider that produced this device. - - - The device class. Free with g_free() after use. - - - - - a #GstDevice - - - - - - Gets the user-friendly name of the device. - - - The device name. Free with g_free() after use. - - - - - a #GstDevice - - - - - - Gets the extra properties of a device. - - - The extra properties or %NULL when there are none. - Free with gst_structure_free() after use. - - - - - a #GstDevice - - - - - - Check if @device matches all of the given classes - - - %TRUE if @device matches. - - - - - a #GstDevice - - - - a "/"-separated list of device classes to match, only match if - all classes are matched - - - - - - Check if @factory matches all of the given classes - - - %TRUE if @device matches. - - - - - a #GstDevice - - - - a %NULL terminated array of classes - to match, only match if all classes are matched - - - - - - - - Tries to reconfigure an existing element to use the device. If this -function fails, then one must destroy the element and create a new one -using gst_device_create_element(). - -Note: This should only be implemented for elements can change their -device in the PLAYING state. - - - %TRUE if the element could be reconfigured to use this device, -%FALSE otherwise. - - - - - a #GstDevice - - - - a #GstElement - - - - - - - - - - - - - - - - - - The parent #GstObject structure. - - - - - - - - - - - - - - - - - - The class structure for a #GstDevice object. - - - The parent #GstObjectClass structure. - - - - - - - a new #GstElement configured to use -this device - - - - - a #GstDevice - - - - name of new element, or %NULL to automatically -create a unique name. - - - - - - - - - - %TRUE if the element could be reconfigured to use this device, -%FALSE otherwise. - - - - - a #GstDevice - - - - a #GstElement - - - - - - - - - - - - - Applications should create a #GstDeviceMonitor when they want -to probe, list and monitor devices of a specific type. The -#GstDeviceMonitor will create the appropriate -#GstDeviceProvider objects and manage them. It will then post -messages on its #GstBus for devices that have been added and -removed. - -The device monitor will monitor all devices matching the filters that -the application has set. - -The basic use pattern of a device monitor is as follows: -|[ - static gboolean - my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data) - { - GstDevice *device; - gchar *name; - - switch (GST_MESSAGE_TYPE (message)) { - case GST_MESSAGE_DEVICE_ADDED: - gst_message_parse_device_added (message, &device); - name = gst_device_get_display_name (device); - g_print("Device added: %s\n", name); - g_free (name); - gst_object_unref (device); - break; - case GST_MESSAGE_DEVICE_REMOVED: - gst_message_parse_device_removed (message, &device); - name = gst_device_get_display_name (device); - g_print("Device removed: %s\n", name); - g_free (name); - gst_object_unref (device); - break; - default: - break; - } - - return G_SOURCE_CONTINUE; - } - - GstDeviceMonitor * - setup_raw_video_source_device_monitor (void) { - GstDeviceMonitor *monitor; - GstBus *bus; - GstCaps *caps; - - monitor = gst_device_monitor_new (); - - bus = gst_device_monitor_get_bus (monitor); - gst_bus_add_watch (bus, my_bus_func, NULL); - gst_object_unref (bus); - - caps = gst_caps_new_empty_simple ("video/x-raw"); - gst_device_monitor_add_filter (monitor, "Video/Source", caps); - gst_caps_unref (caps); - - gst_device_monitor_start (monitor); - - return monitor; - } -]| - - - Create a new #GstDeviceMonitor - - - a new device monitor. - - - - - Adds a filter for which #GstDevice will be monitored, any device that matches -all these classes and the #GstCaps will be returned. - -If this function is called multiple times to add more filters, each will be -matched independently. That is, adding more filters will not further restrict -what devices are matched. - -The #GstCaps supported by the device as returned by gst_device_get_caps() are -not intersected with caps filters added using this function. - -Filters must be added before the #GstDeviceMonitor is started. - - - The id of the new filter or 0 if no provider matched the filter's - classes. - - - - - a device monitor - - - - device classes to use as filter or %NULL for any class - - - - the #GstCaps to filter or %NULL for ANY - - - - - - Gets the #GstBus of this #GstDeviceMonitor - - - a #GstBus - - - - - a #GstDeviceProvider - - - - - - Gets a list of devices from all of the relevant monitors. This may actually -probe the hardware if the monitor is not currently started. - - - a #GList of - #GstDevice - - - - - - - A #GstDeviceProvider - - - - - - Get a list of the currently selected device provider factories. - -This - - - - A list of device provider factory names that are currently being - monitored by @monitor or %NULL when nothing is being monitored. - - - - - - - a #GstDeviceMonitor - - - - - - Get if @monitor is currently showing all devices, even those from hidden -providers. - - - %TRUE when all devices will be shown. - - - - - a #GstDeviceMonitor - - - - - - Removes a filter from the #GstDeviceMonitor using the id that was returned -by gst_device_monitor_add_filter(). - - - %TRUE of the filter id was valid, %FALSE otherwise - - - - - a device monitor - - - - the id of the filter - - - - - - Set if all devices should be visible, even those devices from hidden -providers. Setting @show_all to true might show some devices multiple times. - - - - - - - a #GstDeviceMonitor - - - - show all devices - - - - - - Starts monitoring the devices, one this has succeeded, the -%GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages -will be emitted on the bus when the list of devices changes. - - - %TRUE if the device monitoring could be started - - - - - A #GstDeviceMonitor - - - - - - Stops monitoring the devices. - - - - - - - A #GstDeviceProvider - - - - - - - - - the parent #GstObject structure - - - - - - - - - - - - - Opaque device monitor class structure. - - - the parent #GstObjectClass structure - - - - - - - - - - - - - - - - A #GstDeviceProvider subclass is provided by a plugin that handles devices -if there is a way to programmatically list connected devices. It can also -optionally provide updates to the list of connected devices. - -Each #GstDeviceProvider subclass is a singleton, a plugin should -normally provide a single subclass for all devices. - -Applications would normally use a #GstDeviceMonitor to monitor devices -from all relevant providers. - - - Create a new device providerfactory capable of instantiating objects of the -@type and add the factory to @plugin. - - - %TRUE, if the registering succeeded, %FALSE on error - - - - - #GstPlugin to register the device provider with, or %NULL for - a static device provider. - - - - name of device providers of this type - - - - rank of device provider (higher rank means more importance when autoplugging) - - - - GType of device provider to register - - - - - - - - - - - - - - - - - - - Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED -and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus -when devices are added or removed from the system. - -Since the #GstDeviceProvider is a singleton, -gst_device_provider_start() may already have been called by another -user of the object, gst_device_provider_stop() needs to be called the same -number of times. - -After this function has been called, gst_device_provider_get_devices() will -return the same objects that have been received from the -#GST_MESSAGE_DEVICE_ADDED messages and will no longer probe. - - - %TRUE if the device providering could be started - - - - - A #GstDeviceProvider - - - - - - Decreases the use-count by one. If the use count reaches zero, this -#GstDeviceProvider will stop providering the devices. This needs to be -called the same number of times that gst_device_provider_start() was called. - - - - - - - A #GstDeviceProvider - - - - - - - - - - - - - - - - - Posts a message on the provider's #GstBus to inform applications that -a new device has been added. - -This is for use by subclasses. - -@device's reference count will be incremented, and any floating reference -will be removed (see gst_object_ref_sink()). - - - - - - - a #GstDeviceProvider - - - - a #GstDevice that has been added - - - - - - This function is used when @changed_device was modified into its new form -@device. This will post a `DEVICE_CHANGED` message on the bus to let -the application know that the device was modified. #GstDevice is immutable -for MT. safety purposes so this is an "atomic" way of letting the application -know when a device was modified. - - - - - - - - - - the new version of @changed_device - - - - the old version of the device that has been updated - - - - - - Posts a message on the provider's #GstBus to inform applications that -a device has been removed. - -This is for use by subclasses. - - - - - - - a #GstDeviceProvider - - - - a #GstDevice that has been removed - - - - - - Gets the #GstBus of this #GstDeviceProvider - - - a #GstBus - - - - - a #GstDeviceProvider - - - - - - Gets a list of devices that this provider understands. This may actually -probe the hardware if the provider is not currently started. - -If the provider has been started, this will returned the same #GstDevice -objedcts that have been returned by the #GST_MESSAGE_DEVICE_ADDED messages. - - - a #GList of - #GstDevice - - - - - - - A #GstDeviceProvider - - - - - - Retrieves the factory that was used to create this device provider. - - - the #GstDeviceProviderFactory used for - creating this device provider. no refcounting is needed. - - - - - a #GstDeviceProvider to request the device provider factory of. - - - - - - Get the provider factory names of the #GstDeviceProvider instances that -are hidden by @provider. - - - - a list of hidden providers factory names or %NULL when - nothing is hidden by @provider. Free with g_strfreev. - - - - - - - a #GstDeviceProvider - - - - - - Get metadata with @key in @provider. - - - the metadata for @key. - - - - - provider to get metadata for - - - - the key to get - - - - - - Make @provider hide the devices from the factory with @name. - -This function is used when @provider will also provide the devices reported -by provider factory @name. A monitor should stop monitoring the -device provider with @name to avoid duplicate devices. - - - - - - - a #GstDeviceProvider - - - - a provider factory name - - - - - - Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED -and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus -when devices are added or removed from the system. - -Since the #GstDeviceProvider is a singleton, -gst_device_provider_start() may already have been called by another -user of the object, gst_device_provider_stop() needs to be called the same -number of times. - -After this function has been called, gst_device_provider_get_devices() will -return the same objects that have been received from the -#GST_MESSAGE_DEVICE_ADDED messages and will no longer probe. - - - %TRUE if the device providering could be started - - - - - A #GstDeviceProvider - - - - - - Decreases the use-count by one. If the use count reaches zero, this -#GstDeviceProvider will stop providering the devices. This needs to be -called the same number of times that gst_device_provider_start() was called. - - - - - - - A #GstDeviceProvider - - - - - - Make @provider unhide the devices from factory @name. - -This function is used when @provider will no longer provide the devices -reported by provider factory @name. A monitor should start -monitoring the devices from provider factory @name in order to see -all devices again. - - - - - - - a #GstDeviceProvider - - - - a provider factory name - - - - - - The parent #GstObject - - - - a #GList of the #GstDevice objects - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The structure of the base #GstDeviceProviderClass - - - the parent #GstObjectClass structure - - - - a pointer to the #GstDeviceProviderFactory that creates this - provider - - - - - - - - - - - - - - - - - - - - - - %TRUE if the device providering could be started - - - - - A #GstDeviceProvider - - - - - - - - - - - - - - A #GstDeviceProvider - - - - - - - - - - - - - - - Set @key with @value as metadata in @klass. - - - - - - - class to set metadata for - - - - the key to set - - - - the value to set - - - - - - Set @key with @value as metadata in @klass. - -Same as gst_device_provider_class_add_metadata(), but @value must be a static string -or an inlined string, as it will not be copied. (GStreamer plugins will -be made resident once loaded, so this function can be used even from -dynamically loaded plugins.) - - - - - - - class to set metadata for - - - - the key to set - - - - the value to set - - - - - - Get metadata with @key in @klass. - - - the metadata for @key. - - - - - class to get metadata for - - - - the key to get - - - - - - Sets the detailed information for a #GstDeviceProviderClass. - -> This function is for use in _class_init functions only. - - - - - - - class to set metadata for - - - - The long English name of the device provider. E.g. "File Sink" - - - - String describing the type of device provider, as an - unordered list separated with slashes ('/'). See draft-klass.txt of the - design docs -for more details and common types. E.g: "Sink/File" - - - - Sentence describing the purpose of the device provider. -E.g: "Write stream to a file" - - - - Name and contact details of the author(s). Use \n to separate -multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" - - - - - - Sets the detailed information for a #GstDeviceProviderClass. - -> This function is for use in _class_init functions only. - -Same as gst_device_provider_class_set_metadata(), but @longname, @classification, -@description, and @author must be static strings or inlined strings, as -they will not be copied. (GStreamer plugins will be made resident once -loaded, so this function can be used even from dynamically loaded plugins.) - - - - - - - class to set metadata for - - - - The long English name of the element. E.g. "File Sink" - - - - String describing the type of element, as -an unordered list separated with slashes ('/'). See draft-klass.txt of the -design docs for more details and common types. E.g: "Sink/File" - - - - Sentence describing the purpose of the -element. E.g: "Write stream to a file" - - - - Name and contact details of the author(s). Use \n -to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at -foo.com&gt;" - - - - - - - #GstDeviceProviderFactory is used to create instances of device providers. A -GstDeviceProviderfactory can be added to a #GstPlugin as it is also a -#GstPluginFeature. - -Use the gst_device_provider_factory_find() and -gst_device_provider_factory_get() functions to create device -provider instances or use gst_device_provider_factory_get_by_name() as a -convenient shortcut. - - - Search for an device provider factory of the given name. Refs the returned -device provider factory; caller is responsible for unreffing. - - - #GstDeviceProviderFactory if -found, %NULL otherwise - - - - - name of factory to find - - - - - - Returns the device provider of the type defined by the given device -provider factory. - - - a #GstDeviceProvider or %NULL -if unable to create device provider - - - - - a named factory to instantiate - - - - - - Get a list of factories with a rank greater or equal to @minrank. -The list of factories is returned by decreasing rank. - - - -a #GList of #GstDeviceProviderFactory device providers. Use -gst_plugin_feature_list_free() after usage. - - - - - - - Minimum rank - - - - - - Returns the device provider of the type defined by the given device -providerfactory. - - - the #GstDeviceProvider or %NULL -if the device provider couldn't be created - - - - - factory to instantiate - - - - - - Get the #GType for device providers managed by this factory. The type can -only be retrieved if the device provider factory is loaded, which can be -assured with gst_plugin_feature_load(). - - - the #GType for device providers managed by this factory. - - - - - factory to get managed #GType from - - - - - - Get the metadata on @factory with @key. - - - the metadata with @key on @factory or %NULL -when there was no metadata with the given @key. - - - - - a #GstDeviceProviderFactory - - - - a key - - - - - - Get the available keys for the metadata on @factory. - - - -a %NULL-terminated array of key strings, or %NULL when there is no -metadata. Free with g_strfreev() when no longer needed. - - - - - - - a #GstDeviceProviderFactory - - - - - - Check if @factory matches all of the given @classes - - - %TRUE if @factory matches or if @classes is %NULL. - - - - - a #GstDeviceProviderFactory - - - - a "/" separate list of classes to match, only match - if all classes are matched - - - - - - Check if @factory matches all of the given classes - - - %TRUE if @factory matches. - - - - - a #GstDeviceProviderFactory - - - - a %NULL terminated array - of classes to match, only match if all classes are matched - - - - - - - - - The opaque #GstDeviceProviderFactoryClass data structure. - - - - - - - A fundamental type that describes a #gdouble range - - - #GstDynamicTypeFactory is used to represent a type that can be -automatically loaded the first time it is used. For example, -a non-standard type for use in caps fields. - -In general, applications and plugins don't need to use the factory -beyond registering the type in a plugin init function. Once that is -done, the type is stored in the registry, and ready as soon as the -registry is loaded. - -## Registering a type for dynamic loading - -|[<!-- language="C" --> - -static gboolean -plugin_init (GstPlugin * plugin) -{ - return gst_dynamic_type_register (plugin, GST_TYPE_CUSTOM_CAPS_FIELD); -} -]| - - - - - - - - - - - - - - - - - - - - - - - - - Get the message bus of this element. This is not thread-safe by default -(i.e. you will have to make sure the object lock is taken yourself). -If in doubt use gst_element_get_bus() instead. - - - - A #GstElement to query - - - - - - - - - - - - - - - - - - - Get the clock of this element.This is not thread-safe by default -(i.e. you will have to make sure it is safe yourself). -If in doubt use gst_element_get_clock() instead. - - - - A #GstElement to query - - - - - Utility function that elements can use in case they encountered a fatal -data processing error. The pipeline will post an error message and the -application will be requested to stop further media processing. - - - - the element that generates the error - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - - - Utility function that elements can use in case they encountered a fatal -data processing error. The pipeline will post an error message and the -application will be requested to stop further media processing. - - - - the element that generates the error - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - optional name, type, value triplets, which will be stored - in the associated GstStructure. NULL terminator required. - Must be enclosed within parentheses. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Elements interacting with hardware devices should specify this classifier in -their metadata. You may need to put the element in "READY" state to test if -the hardware is present in the system. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Elements of any of the defined GST_ELEMENT_FACTORY_LIST types - - - - - All sinks handling audio, video or image media types - - - - - All encoders handling audio media types - - - - - All elements used to 'decode' streams (decoders, demuxers, parsers, depayloaders) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Elements matching any of the defined GST_ELEMENT_FACTORY_TYPE_MEDIA types - -Note: Do not use this if you wish to not filter against any of the defined -media types. If you wish to do this, simply don't specify any -GST_ELEMENT_FACTORY_TYPE_MEDIA flag. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - All encoders handling video or image media types - - - - - Utility function that elements can use in case they encountered a fatal -data processing error due to wrong flow processing. - - - - the element that generates the error - - - the GstFlowReturn leading to that ERROR message - - - - - - - - - - - - Utility function that elements can use in case they want to inform -the application of something noteworthy that is not an error. -The pipeline will post a info message and the -application will be informed. - - - - the element that generates the information - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - - - Utility function that elements can use in case they want to inform -the application of something noteworthy that is not an error. -The pipeline will post a info message and the -application will be informed. -Optional name, type, value triplets may be supplied, and will be stored -in the associated GstStructure. NULL terminator required. - - - - the element that generates the information - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - optional name, type, value triplets, which will be stored - in the associated GstStructure. NULL terminator required. - Must be enclosed within parentheses. - - - - - Check if the element is in the locked state and therefore will ignore state -changes from its parent object. - - - - A #GstElement to query - - - - - - - - - - - - Name and contact details of the author(s). Use \n to separate -multiple author details. -E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" - - - - - Sentence describing the purpose of the element. -E.g: "Write stream to a file" - - - - - Set uri pointing to user documentation. Applications can use this to show -help for e.g. effects to users. - - - - - Elements that bridge to certain other products can include an icon of that -used product. Application can show the icon in menus/selectors to help -identifying specific elements. - - - - - String describing the type of element, as an unordered list -separated with slashes ('/'). See draft-klass.txt of the design docs -for more details and common types. E.g: "Sink/File" - - - - - The long English name of the element. E.g. "File Sink" - - - - - Gets the name of this element. This is not thread-safe by default -(i.e. you will have to make sure the object lock is taken yourself). -If in doubt use gst_element_get_name() instead. - - - - A #GstElement to query - - - - - Get the pads of this elements. - - - - A #GstElement to query - - - - - Get the parent object of this element. This is not thread-safe by default -(i.e. you will have to make sure the object lock is taken yourself). -If in doubt use gst_object_get_parent() instead. - - - - A #GstElement to query - - - - - This macro returns the start_time of the @elem. The start_time is the -running_time of the pipeline when the element went to PAUSED. - - - - a #GstElement to return the start time for. - - - - - Utility function that elements can use in case they encountered a non-fatal -data processing problem. The pipeline will post a warning message and the -application will be informed. - - - - the element that generates the warning - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - - - Utility function that elements can use in case they encountered a non-fatal -data processing problem. The pipeline will post a warning message and the -application will be informed. - - - - the element that generates the warning - - - like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) - - - error code defined for that domain (see [GstGError](gsterror)) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - optional name, type, value triplets, which will be stored - in the associated GstStructure. NULL terminator required. - Must be enclosed within parentheses. - - - - - Builds a string using errno describing the previously failed system -call. To be used as the debug argument in #GST_ELEMENT_ERROR. - - - - - - - - - - - - - - - - - - - Check if an event can travel downstream. - - - - the event to query - - - - - Check if an event is serialized with the data stream. - - - - the event to query - - - - - Check if an event is sticky on the pads. - - - - the event to query - - - - - Check if an event can travel upstream. - - - - the event to query - - - - - when making custom event types, use this macro with the num and -the given flags - - - - the event number to create - - - the event flags - - - - - - - - - The sequence number of @event. - - - - the event to query - - - - - Get the #GstClockTime timestamp of the event. This is the time when the event -was created. - - - - the event to query - - - - - Get the #GstEventType of the event. - - - - the event to query - - - - - The same thing as #GST_EVENT_TYPE_UPSTREAM | #GST_EVENT_TYPE_DOWNSTREAM. - - - - - Get a constant string representation of the #GstEventType of the event. - - - - the event to query - - - - - GstElement is the abstract base class needed to construct an element that -can be used in a GStreamer pipeline. Please refer to the plugin writers -guide for more information on creating #GstElement subclasses. - -The name of a #GstElement can be get with gst_element_get_name() and set with -gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the -core when using the appropriate locking. Do not use this in plug-ins or -applications in order to retain ABI compatibility. - -Elements can have pads (of the type #GstPad). These pads link to pads on -other elements. #GstBuffer flow between these linked pads. -A #GstElement has a #GList of #GstPad structures for all their input (or sink) -and output (or source) pads. -Core and plug-in writers can add and remove pads with gst_element_add_pad() -and gst_element_remove_pad(). - -An existing pad of an element can be retrieved by name with -gst_element_get_static_pad(). A new dynamic pad can be created using -gst_element_request_pad() with a #GstPadTemplate. -An iterator of all pads can be retrieved with gst_element_iterate_pads(). - -Elements can be linked through their pads. -If the link is straightforward, use the gst_element_link() -convenience function to link two elements, or gst_element_link_many() -for more elements in a row. -Use gst_element_link_filtered() to link two elements constrained by -a specified set of #GstCaps. -For finer control, use gst_element_link_pads() and -gst_element_link_pads_filtered() to specify the pads to link on -each element by name. - -Each element has a state (see #GstState). You can get and set the state -of an element with gst_element_get_state() and gst_element_set_state(). -Setting a state triggers a #GstStateChange. To get a string representation -of a #GstState, use gst_element_state_get_name(). - -You can get and set a #GstClock on an element using gst_element_get_clock() -and gst_element_set_clock(). -Some elements can provide a clock for the pipeline if -the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the -gst_element_provide_clock() method one can retrieve the clock provided by -such an element. -Not all elements require a clock to operate correctly. If the -#GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the -element with gst_element_set_clock(). - -Note that clock selection and distribution is normally handled by the -toplevel #GstPipeline so the clock functions are only to be used in very -specific situations. - - - Creates an element for handling the given URI. - - - a new element or %NULL if none -could be created - - - - - Whether to create a source or a sink - - - - URI to create an element for - - - - Name of created element, can be %NULL. - - - - - - Create a new elementfactory capable of instantiating objects of the -@type and add the factory to @plugin. - - - %TRUE, if the registering succeeded, %FALSE on error - - - - - #GstPlugin to register the element with, or %NULL for - a static element. - - - - name of elements of this type - - - - rank of element (higher rank means more importance when autoplugging) - - - - GType of element to register - - - - - - Gets a string representing the given state change result. - - - a string with the name of the state - result. - - - - - a #GstStateChangeReturn to get the name of. - - - - - - Gets a string representing the given state. - - - a string with the name of the state. - - - - - a #GstState to get the name of. - - - - - - Perform @transition on @element. - -This function must be called with STATE_LOCK held and is mainly used -internally. - - - the #GstStateChangeReturn of the state transition. - - - - - a #GstElement - - - - the requested transition - - - - - - Gets the state of the element. - -For elements that performed an ASYNC state change, as reported by -gst_element_set_state(), this function will block up to the -specified timeout value for the state change to complete. -If the element completes the state change or goes into -an error, this function returns immediately with a return value of -%GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively. - -For elements that did not return %GST_STATE_CHANGE_ASYNC, this function -returns the current and pending state immediately. - -This function returns %GST_STATE_CHANGE_NO_PREROLL if the element -successfully changed its state but is not able to provide data yet. -This mostly happens for live sources that only produce data in -%GST_STATE_PLAYING. While the state change return is equivalent to -%GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that -some sink elements might not be able to complete their state change because -an element is not producing data to complete the preroll. When setting the -element to playing, the preroll will complete and playback will start. - - - %GST_STATE_CHANGE_SUCCESS if the element has no more pending state - and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the - element is still performing a state change or - %GST_STATE_CHANGE_FAILURE if the last state change failed. - -MT safe. - - - - - a #GstElement to get the state of. - - - - a pointer to #GstState to hold the state. - Can be %NULL. - - - - a pointer to #GstState to hold the pending - state. Can be %NULL. - - - - a #GstClockTime to specify the timeout for an async - state change or %GST_CLOCK_TIME_NONE for infinite timeout. - - - - - - Use this function to signal that the element does not expect any more pads -to show up in the current pipeline. This function should be called whenever -pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES -pad templates use this in combination with autopluggers to figure out that -the element is done initializing its pads. - -This function emits the #GstElement::no-more-pads signal. - -MT safe. - - - - - - - a #GstElement - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Post a message on the element's #GstBus. This function takes ownership of the -message; if you want to access the message after this call, you should add an -additional reference before calling. - - - %TRUE if the message was successfully posted. The function returns -%FALSE if the element did not have a bus. - -MT safe. - - - - - a #GstElement posting the message - - - - a #GstMessage to post - - - - - - Get the clock provided by the given element. -> An element is only required to provide a clock in the PAUSED -> state. Some elements can provide a clock in other states. - - - the GstClock provided by the -element or %NULL if no clock could be provided. Unref after usage. - -MT safe. - - - - - a #GstElement to query - - - - - - Performs a query on the given element. - -For elements that don't implement a query handler, this function -forwards the query to a random srcpad or to the peer of a -random linked sinkpad of this element. - -Please note that some queries might need a running pipeline to work. - - - %TRUE if the query could be performed. - -MT safe. - - - - - a #GstElement to perform the query on. - - - - the #GstQuery. - - - - - - - - - - - - - - - - - - - - Retrieves a request pad from the element according to the provided template. -Pad templates can be looked up using -gst_element_factory_get_static_pad_templates(). - -The pad should be released with gst_element_release_request_pad(). - - - requested #GstPad if found, - otherwise %NULL. Release after usage. - - - - - a #GstElement to find a request pad of. - - - - a #GstPadTemplate of which we want a pad of. - - - - the name of the request #GstPad -to retrieve. Can be %NULL. - - - - the caps of the pad we want to -request. Can be %NULL. - - - - - - Sends an event to an element. If the element doesn't implement an -event handler, the event will be pushed on a random linked sink pad for -downstream events or a random linked source pad for upstream events. - -This function takes ownership of the provided event so you should -gst_event_ref() it if you want to reuse the event after this call. - -MT safe. - - - %TRUE if the event was handled. Events that trigger a preroll (such -as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. - - - - - a #GstElement to send the event to. - - - - the #GstEvent to send to the element. - - - - - - Sets the bus of the element. Increases the refcount on the bus. -For internal use only, unless you're testing elements. - -MT safe. - - - - - - - a #GstElement to set the bus of. - - - - the #GstBus to set. - - - - - - Sets the clock for the element. This function increases the -refcount on the clock. Any previously set clock on the object -is unreffed. - - - %TRUE if the element accepted the clock. An element can refuse a -clock when it, for example, is not able to slave its internal clock to the -@clock or when it requires a specific clock to operate. - -MT safe. - - - - - a #GstElement to set the clock for. - - - - the #GstClock to set for the element. - - - - - - Sets the context of the element. Increases the refcount of the context. - -MT safe. - - - - - - - a #GstElement to set the context of. - - - - the #GstContext to set. - - - - - - Sets the state of the element. This function will try to set the -requested state by going through all the intermediary states and calling -the class's state change function for each. - -This function can return #GST_STATE_CHANGE_ASYNC, in which case the -element will perform the remainder of the state change asynchronously in -another thread. -An application can use gst_element_get_state() to wait for the completion -of the state change or it can wait for a %GST_MESSAGE_ASYNC_DONE or -%GST_MESSAGE_STATE_CHANGED on the bus. - -State changes to %GST_STATE_READY or %GST_STATE_NULL never return -#GST_STATE_CHANGE_ASYNC. - - - Result of the state change using #GstStateChangeReturn. - -MT safe. - - - - - a #GstElement to change state of. - - - - the element's new #GstState. - - - - - - - - - - - - - - - - - - - - - - - - - - Abort the state change of the element. This function is used -by elements that do asynchronous state changes and find out -something is wrong. - -This function should be called with the STATE_LOCK held. - -MT safe. - - - - - - - a #GstElement to abort the state of. - - - - - - Adds a pad (link point) to @element. @pad's parent will be set to @element; -see gst_object_set_parent() for refcounting information. - -Pads are automatically activated when added in the PAUSED or PLAYING -state. - -The pad and the element should be unlocked when calling this function. - -This function will emit the #GstElement::pad-added signal on the element. - - - %TRUE if the pad could be added. This function can fail when -a pad with the same name already existed or the pad already had another -parent. - -MT safe. - - - - - a #GstElement to add the pad to. - - - - the #GstPad to add to the element. - - - - - - - - a watch id, which can be used in connection with - gst_element_remove_property_notify_watch() to remove the watch again. - - - - - a #GstElement to watch (recursively) for property changes - - - - name of property to watch for changes, or - NULL to watch all properties - - - - whether to include the new property value in the message - - - - - - - - a watch id, which can be used in connection with - gst_element_remove_property_notify_watch() to remove the watch again. - - - - - a #GstElement to watch for property changes - - - - name of property to watch for changes, or - NULL to watch all properties - - - - whether to include the new property value in the message - - - - - - Calls @func from another thread and passes @user_data to it. This is to be -used for cases when a state change has to be performed from a streaming -thread, directly via gst_element_set_state() or indirectly e.g. via SEEK -events. - -Calling those functions directly from the streaming thread will cause -deadlocks in many situations, as they might involve waiting for the -streaming thread to shut down from this very streaming thread. - -MT safe. - - - - - - - a #GstElement - - - - Function to call asynchronously from another thread - - - - Data to pass to @func - - - - GDestroyNotify for @user_data - - - - - - Perform @transition on @element. - -This function must be called with STATE_LOCK held and is mainly used -internally. - - - the #GstStateChangeReturn of the state transition. - - - - - a #GstElement - - - - the requested transition - - - - - - Commit the state change of the element and proceed to the next -pending state if any. This function is used -by elements that do asynchronous state changes. -The core will normally call this method automatically when an -element returned %GST_STATE_CHANGE_SUCCESS from the state change function. - -If after calling this method the element still has not reached -the pending state, the next state change is performed. - -This method is used internally and should normally not be called by plugins -or applications. - -This function must be called with STATE_LOCK held. - - - The result of the commit state change. - -MT safe. - - - - - a #GstElement to continue the state change of. - - - - The previous state return value - - - - - - Creates a pad for each pad template that is always available. -This function is only useful during object initialization of -subclasses of #GstElement. - - - - - - - a #GstElement to create pads for - - - - - - Call @func with @user_data for each of @element's pads. @func will be called -exactly once for each pad that exists at the time of this call, unless -one of the calls to @func returns %FALSE in which case we will stop -iterating pads and return early. If new pads are added or pads are removed -while pads are being iterated, this will not be taken into account until -next time this function is used. - - - %FALSE if @element had no pads or if one of the calls to @func - returned %FALSE. - - - - - a #GstElement to iterate pads of - - - - function to call for each pad - - - - user data passed to @func - - - - - - Call @func with @user_data for each of @element's sink pads. @func will be -called exactly once for each sink pad that exists at the time of this call, -unless one of the calls to @func returns %FALSE in which case we will stop -iterating pads and return early. If new sink pads are added or sink pads -are removed while the sink pads are being iterated, this will not be taken -into account until next time this function is used. - - - %FALSE if @element had no sink pads or if one of the calls to @func - returned %FALSE. - - - - - a #GstElement to iterate sink pads of - - - - function to call for each sink pad - - - - user data passed to @func - - - - - - Call @func with @user_data for each of @element's source pads. @func will be -called exactly once for each source pad that exists at the time of this call, -unless one of the calls to @func returns %FALSE in which case we will stop -iterating pads and return early. If new source pads are added or source pads -are removed while the source pads are being iterated, this will not be taken -into account until next time this function is used. - - - %FALSE if @element had no source pads or if one of the calls - to @func returned %FALSE. - - - - - a #GstElement to iterate source pads of - - - - function to call for each source pad - - - - user data passed to @func - - - - - - Returns the base time of the element. The base time is the -absolute time of the clock when this element was last put to -PLAYING. Subtracting the base time from the clock time gives -the running time of the element. - - - the base time of the element. - -MT safe. - - - - - a #GstElement. - - - - - - Returns the bus of the element. Note that only a #GstPipeline will provide a -bus for the application. - - - the element's #GstBus. unref after -usage. - -MT safe. - - - - - a #GstElement to get the bus of. - - - - - - Gets the currently configured clock of the element. This is the clock as was -last set with gst_element_set_clock(). - -Elements in a pipeline will only have their clock set when the -pipeline is in the PLAYING state. - - - the #GstClock of the element. unref after usage. - -MT safe. - - - - - a #GstElement to get the clock of. - - - - - - Looks for an unlinked pad to which the given pad can link. It is not -guaranteed that linking the pads will work, though it should work in most -cases. - -This function will first attempt to find a compatible unlinked ALWAYS pad, -and if none can be found, it will request a compatible REQUEST pad by looking -at the templates of @element. - - - the #GstPad to which a link - can be made, or %NULL if one cannot be found. gst_object_unref() - after usage. - - - - - a #GstElement in which the pad should be found. - - - - the #GstPad to find a compatible one for. - - - - the #GstCaps to use as a filter. - - - - - - Retrieves a pad template from @element that is compatible with @compattempl. -Pads from compatible templates can be linked together. - - - a compatible #GstPadTemplate, - or %NULL if none was found. No unreferencing is necessary. - - - - - a #GstElement to get a compatible pad template for - - - - the #GstPadTemplate to find a compatible - template for - - - - - - Gets the context with @context_type set on the element or NULL. - -MT safe. - - - A #GstContext or NULL - - - - - a #GstElement to get the context of. - - - - a name of a context to retrieve - - - - - - Gets the context with @context_type set on the element or NULL. - - - A #GstContext or NULL - - - - - a #GstElement to get the context of. - - - - a name of a context to retrieve - - - - - - Gets the contexts set on the element. - -MT safe. - - - List of #GstContext - - - - - - - a #GstElement to set the context of. - - - - - - Returns the current clock time of the element, as in, the time of the -element's clock, or GST_CLOCK_TIME_NONE if there is no clock. - - - the clock time of the element, or GST_CLOCK_TIME_NONE if there is -no clock. - - - - - a #GstElement. - - - - - - Returns the running time of the element. The running time is the -element's clock time minus its base time. Will return GST_CLOCK_TIME_NONE -if the element has no clock, or if its base time has not been set. - - - the running time of the element, or GST_CLOCK_TIME_NONE if the -element has no clock or its base time has not been set. - - - - - a #GstElement. - - - - - - Retrieves the factory that was used to create this element. - - - the #GstElementFactory used for creating this - element or %NULL if element has not been registered (static element). no refcounting is needed. - - - - - a #GstElement to request the element factory of. - - - - - - Get metadata with @key in @klass. - - - the metadata for @key. - - - - - class to get metadata for - - - - the key to get - - - - - - Retrieves a padtemplate from @element with the given name. - - - the #GstPadTemplate with the - given name, or %NULL if none was found. No unreferencing is - necessary. - - - - - a #GstElement to get the pad template of. - - - - the name of the #GstPadTemplate to get. - - - - - - Retrieves a list of the pad templates associated with @element. The -list must not be modified by the calling code. - - - the #GList of - pad templates. - - - - - - - a #GstElement to get pad templates of. - - - - - - Retrieves a pad from the element by name (e.g. "src_\%d"). This version only -retrieves request pads. The pad should be released with -gst_element_release_request_pad(). - -This method is slower than manually getting the pad template and calling -gst_element_request_pad() if the pads should have a specific name (e.g. -@name is "src_1" instead of "src_\%u"). - - - requested #GstPad if found, - otherwise %NULL. Release after usage. - - - - - a #GstElement to find a request pad of. - - - - the name of the request #GstPad to retrieve. - - - - - - Returns the start time of the element. The start time is the -running time of the clock when this element was last put to PAUSED. - -Usually the start_time is managed by a toplevel element such as -#GstPipeline. - -MT safe. - - - the start time of the element. - - - - - a #GstElement. - - - - - - Gets the state of the element. - -For elements that performed an ASYNC state change, as reported by -gst_element_set_state(), this function will block up to the -specified timeout value for the state change to complete. -If the element completes the state change or goes into -an error, this function returns immediately with a return value of -%GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively. - -For elements that did not return %GST_STATE_CHANGE_ASYNC, this function -returns the current and pending state immediately. - -This function returns %GST_STATE_CHANGE_NO_PREROLL if the element -successfully changed its state but is not able to provide data yet. -This mostly happens for live sources that only produce data in -%GST_STATE_PLAYING. While the state change return is equivalent to -%GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that -some sink elements might not be able to complete their state change because -an element is not producing data to complete the preroll. When setting the -element to playing, the preroll will complete and playback will start. - - - %GST_STATE_CHANGE_SUCCESS if the element has no more pending state - and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the - element is still performing a state change or - %GST_STATE_CHANGE_FAILURE if the last state change failed. - -MT safe. - - - - - a #GstElement to get the state of. - - - - a pointer to #GstState to hold the state. - Can be %NULL. - - - - a pointer to #GstState to hold the pending - state. Can be %NULL. - - - - a #GstClockTime to specify the timeout for an async - state change or %GST_CLOCK_TIME_NONE for infinite timeout. - - - - - - Retrieves a pad from @element by name. This version only retrieves -already-existing (i.e. 'static') pads. - - - the requested #GstPad if - found, otherwise %NULL. unref after usage. - -MT safe. - - - - - a #GstElement to find a static pad of. - - - - the name of the static #GstPad to retrieve. - - - - - - Checks if the state of an element is locked. -If the state of an element is locked, state changes of the parent don't -affect the element. -This way you can leave currently unused elements inside bins. Just lock their -state before changing the state from #GST_STATE_NULL. - -MT safe. - - - %TRUE, if the element's state is locked. - - - - - a #GstElement. - - - - - - Retrieves an iterator of @element's pads. The iterator should -be freed after usage. Also more specialized iterators exists such as -gst_element_iterate_src_pads() or gst_element_iterate_sink_pads(). - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - - - the #GstIterator of #GstPad. - -MT safe. - - - - - a #GstElement to iterate pads of. - - - - - - Retrieves an iterator of @element's sink pads. - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - - - the #GstIterator of #GstPad. - -MT safe. - - - - - a #GstElement. - - - - - - Retrieves an iterator of @element's source pads. - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - - - the #GstIterator of #GstPad. - -MT safe. - - - - - a #GstElement. - - - - - - Links @src to @dest. The link must be from source to -destination; the other direction will not be tried. The function looks for -existing pads that aren't linked yet. It will request new pads if necessary. -Such pads need to be released manually when unlinking. -If multiple links are possible, only one is established. - -Make sure you have added your elements to a bin or pipeline with -gst_bin_add() before trying to link them. - - - %TRUE if the elements could be linked, %FALSE otherwise. - - - - - a #GstElement containing the source pad. - - - - the #GstElement containing the destination pad. - - - - - - Links @src to @dest using the given caps as filtercaps. -The link must be from source to -destination; the other direction will not be tried. The function looks for -existing pads that aren't linked yet. It will request new pads if necessary. -If multiple links are possible, only one is established. - -Make sure you have added your elements to a bin or pipeline with -gst_bin_add() before trying to link them. - - - %TRUE if the pads could be linked, %FALSE otherwise. - - - - - a #GstElement containing the source pad. - - - - the #GstElement containing the destination pad. - - - - the #GstCaps to filter the link, - or %NULL for no filter. - - - - - - Chain together a series of elements. Uses gst_element_link(). -Make sure you have added your elements to a bin or pipeline with -gst_bin_add() before trying to link them. - - - %TRUE on success, %FALSE otherwise. - - - - - the first #GstElement in the link chain. - - - - the second #GstElement in the link chain. - - - - the %NULL-terminated list of elements to link in order. - - - - - - Links the two named pads of the source and destination elements. -Side effect is that if one of the pads has no parent, it becomes a -child of the parent of the other element. If they have different -parents, the link fails. - - - %TRUE if the pads could be linked, %FALSE otherwise. - - - - - a #GstElement containing the source pad. - - - - the name of the #GstPad in source element - or %NULL for any pad. - - - - the #GstElement containing the destination pad. - - - - the name of the #GstPad in destination element, -or %NULL for any pad. - - - - - - Links the two named pads of the source and destination elements. Side effect -is that if one of the pads has no parent, it becomes a child of the parent of -the other element. If they have different parents, the link fails. If @caps -is not %NULL, makes sure that the caps of the link is a subset of @caps. - - - %TRUE if the pads could be linked, %FALSE otherwise. - - - - - a #GstElement containing the source pad. - - - - the name of the #GstPad in source element - or %NULL for any pad. - - - - the #GstElement containing the destination pad. - - - - the name of the #GstPad in destination element - or %NULL for any pad. - - - - the #GstCaps to filter the link, - or %NULL for no filter. - - - - - - Links the two named pads of the source and destination elements. -Side effect is that if one of the pads has no parent, it becomes a -child of the parent of the other element. If they have different -parents, the link fails. - -Calling gst_element_link_pads_full() with @flags == %GST_PAD_LINK_CHECK_DEFAULT -is the same as calling gst_element_link_pads() and the recommended way of -linking pads with safety checks applied. - -This is a convenience function for gst_pad_link_full(). - - - %TRUE if the pads could be linked, %FALSE otherwise. - - - - - a #GstElement containing the source pad. - - - - the name of the #GstPad in source element - or %NULL for any pad. - - - - the #GstElement containing the destination pad. - - - - the name of the #GstPad in destination element, -or %NULL for any pad. - - - - the #GstPadLinkCheck to be performed when linking pads. - - - - - - Brings the element to the lost state. The current state of the -element is copied to the pending state so that any call to -gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC. - -An ASYNC_START message is posted. If the element was PLAYING, it will -go to PAUSED. The element will be restored to its PLAYING state by -the parent pipeline when it prerolls again. - -This is mostly used for elements that lost their preroll buffer -in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush, -they will go to their pending state again when a new preroll buffer is -queued. This function can only be called when the element is currently -not in error or an async state change. - -This function is used internally and should normally not be called from -plugins or applications. - - - - - - - a #GstElement the state is lost of - - - - - - Post an error, warning or info message on the bus from inside an element. - -@type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or -#GST_MESSAGE_INFO. - -MT safe. - - - - - - - a #GstElement to send message from - - - - the #GstMessageType - - - - the GStreamer GError domain this message belongs to - - - - the GError code belonging to the domain - - - - an allocated text string to be used - as a replacement for the default message connected to code, - or %NULL - - - - an allocated debug message to be - used as a replacement for the default debugging information, - or %NULL - - - - the source code file where the error was generated - - - - the source code function where the error was generated - - - - the source code line where the error was generated - - - - - - Post an error, warning or info message on the bus from inside an element. - -@type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or -#GST_MESSAGE_INFO. - - - - - - - a #GstElement to send message from - - - - the #GstMessageType - - - - the GStreamer GError domain this message belongs to - - - - the GError code belonging to the domain - - - - an allocated text string to be used - as a replacement for the default message connected to code, - or %NULL - - - - an allocated debug message to be - used as a replacement for the default debugging information, - or %NULL - - - - the source code file where the error was generated - - - - the source code function where the error was generated - - - - the source code line where the error was generated - - - - optional details structure - - - - - - Use this function to signal that the element does not expect any more pads -to show up in the current pipeline. This function should be called whenever -pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES -pad templates use this in combination with autopluggers to figure out that -the element is done initializing its pads. - -This function emits the #GstElement::no-more-pads signal. - -MT safe. - - - - - - - a #GstElement - - - - - - Post a message on the element's #GstBus. This function takes ownership of the -message; if you want to access the message after this call, you should add an -additional reference before calling. - - - %TRUE if the message was successfully posted. The function returns -%FALSE if the element did not have a bus. - -MT safe. - - - - - a #GstElement posting the message - - - - a #GstMessage to post - - - - - - Get the clock provided by the given element. -> An element is only required to provide a clock in the PAUSED -> state. Some elements can provide a clock in other states. - - - the GstClock provided by the -element or %NULL if no clock could be provided. Unref after usage. - -MT safe. - - - - - a #GstElement to query - - - - - - Performs a query on the given element. - -For elements that don't implement a query handler, this function -forwards the query to a random srcpad or to the peer of a -random linked sinkpad of this element. - -Please note that some queries might need a running pipeline to work. - - - %TRUE if the query could be performed. - -MT safe. - - - - - a #GstElement to perform the query on. - - - - the #GstQuery. - - - - - - Queries an element to convert @src_val in @src_format to @dest_format. - - - %TRUE if the query could be performed. - - - - - a #GstElement to invoke the convert query on. - - - - a #GstFormat to convert from. - - - - a value to convert. - - - - the #GstFormat to convert to. - - - - a pointer to the result. - - - - - - Queries an element (usually top-level pipeline or playbin element) for the -total stream duration in nanoseconds. This query will only work once the -pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application -will receive an ASYNC_DONE message on the pipeline bus when that is the case. - -If the duration changes for some reason, you will get a DURATION_CHANGED -message on the pipeline bus, in which case you should re-query the duration -using this function. - - - %TRUE if the query could be performed. - - - - - a #GstElement to invoke the duration query on. - - - - the #GstFormat requested - - - - A location in which to store the total duration, or %NULL. - - - - - - Queries an element (usually top-level pipeline or playbin element) for the -stream position in nanoseconds. This will be a value between 0 and the -stream duration (if the stream duration is known). This query will usually -only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING -state). The application will receive an ASYNC_DONE message on the pipeline -bus when that is the case. - -If one repeatedly calls this function one can also create a query and reuse -it in gst_element_query(). - - - %TRUE if the query could be performed. - - - - - a #GstElement to invoke the position query on. - - - - the #GstFormat requested - - - - a location in which to store the current - position, or %NULL. - - - - - - Makes the element free the previously requested pad as obtained -with gst_element_request_pad(). - -This does not unref the pad. If the pad was created by using -gst_element_request_pad(), gst_element_release_request_pad() needs to be -followed by gst_object_unref() to free the @pad. - -MT safe. - - - - - - - a #GstElement to release the request pad of. - - - - the #GstPad to release. - - - - - - Removes @pad from @element. @pad will be destroyed if it has not been -referenced elsewhere using gst_object_unparent(). - -This function is used by plugin developers and should not be used -by applications. Pads that were dynamically requested from elements -with gst_element_request_pad() should be released with the -gst_element_release_request_pad() function instead. - -Pads are not automatically deactivated so elements should perform the needed -steps to deactivate the pad in case this pad is removed in the PAUSED or -PLAYING state. See gst_pad_set_active() for more information about -deactivating pads. - -The pad and the element should be unlocked when calling this function. - -This function will emit the #GstElement::pad-removed signal on the element. - - - %TRUE if the pad could be removed. Can return %FALSE if the -pad does not belong to the provided element. - -MT safe. - - - - - a #GstElement to remove pad from. - - - - the #GstPad to remove from the element. - - - - - - - - - - - - a #GstElement being watched for property changes - - - - watch id to remove - - - - - - Retrieves a request pad from the element according to the provided template. -Pad templates can be looked up using -gst_element_factory_get_static_pad_templates(). - -The pad should be released with gst_element_release_request_pad(). - - - requested #GstPad if found, - otherwise %NULL. Release after usage. - - - - - a #GstElement to find a request pad of. - - - - a #GstPadTemplate of which we want a pad of. - - - - the name of the request #GstPad -to retrieve. Can be %NULL. - - - - the caps of the pad we want to -request. Can be %NULL. - - - - - - Sends a seek event to an element. See gst_event_new_seek() for the details of -the parameters. The seek event is sent to the element using -gst_element_send_event(). - -MT safe. - - - %TRUE if the event was handled. Flushing seeks will trigger a -preroll, which will emit %GST_MESSAGE_ASYNC_DONE. - - - - - a #GstElement to send the event to. - - - - The new playback rate - - - - The format of the seek values - - - - The optional seek flags. - - - - The type and flags for the new start position - - - - The value of the new start position - - - - The type and flags for the new stop position - - - - The value of the new stop position - - - - - - Simple API to perform a seek on the given element, meaning it just seeks -to the given position relative to the start of the stream. For more complex -operations like segment seeks (e.g. for looping) or changing the playback -rate or seeking relative to the last configured playback segment you should -use gst_element_seek(). - -In a completely prerolled PAUSED or PLAYING pipeline, seeking is always -guaranteed to return %TRUE on a seekable media type or %FALSE when the media -type is certainly not seekable (such as a live stream). - -Some elements allow for seeking in the READY state, in this -case they will store the seek event and execute it when they are put to -PAUSED. If the element supports seek in READY, it will always return %TRUE when -it receives the event in the READY state. - - - %TRUE if the seek operation succeeded. Flushing seeks will trigger a -preroll, which will emit %GST_MESSAGE_ASYNC_DONE. - - - - - a #GstElement to seek on - - - - a #GstFormat to execute the seek in, such as #GST_FORMAT_TIME - - - - seek options; playback applications will usually want to use - GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here - - - - position to seek to (relative to the start); if you are doing - a seek in #GST_FORMAT_TIME this value is in nanoseconds - - multiply with #GST_SECOND to convert seconds to nanoseconds or - with #GST_MSECOND to convert milliseconds to nanoseconds. - - - - - - Sends an event to an element. If the element doesn't implement an -event handler, the event will be pushed on a random linked sink pad for -downstream events or a random linked source pad for upstream events. - -This function takes ownership of the provided event so you should -gst_event_ref() it if you want to reuse the event after this call. - -MT safe. - - - %TRUE if the event was handled. Events that trigger a preroll (such -as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. - - - - - a #GstElement to send the event to. - - - - the #GstEvent to send to the element. - - - - - - Set the base time of an element. See gst_element_get_base_time(). - -MT safe. - - - - - - - a #GstElement. - - - - the base time to set. - - - - - - Sets the bus of the element. Increases the refcount on the bus. -For internal use only, unless you're testing elements. - -MT safe. - - - - - - - a #GstElement to set the bus of. - - - - the #GstBus to set. - - - - - - Sets the clock for the element. This function increases the -refcount on the clock. Any previously set clock on the object -is unreffed. - - - %TRUE if the element accepted the clock. An element can refuse a -clock when it, for example, is not able to slave its internal clock to the -@clock or when it requires a specific clock to operate. - -MT safe. - - - - - a #GstElement to set the clock for. - - - - the #GstClock to set for the element. - - - - - - Sets the context of the element. Increases the refcount of the context. - -MT safe. - - - - - - - a #GstElement to set the context of. - - - - the #GstContext to set. - - - - - - Locks the state of an element, so state changes of the parent don't affect -this element anymore. - -Note that this is racy if the state lock of the parent bin is not taken. -The parent bin might've just checked the flag in another thread and as the -next step proceed to change the child element's state. - -MT safe. - - - %TRUE if the state was changed, %FALSE if bad parameters were given -or the elements state-locking needed no change. - - - - - a #GstElement - - - - %TRUE to lock the element's state - - - - - - Set the start time of an element. The start time of the element is the -running time of the element when it last went to the PAUSED state. In READY -or after a flushing seek, it is set to 0. - -Toplevel elements like #GstPipeline will manage the start_time and -base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE -on such a toplevel element will disable the distribution of the base_time to -the children and can be useful if the application manages the base_time -itself, for example if you want to synchronize capture from multiple -pipelines, and you can also ensure that the pipelines have the same clock. - -MT safe. - - - - - - - a #GstElement. - - - - the base time to set. - - - - - - Sets the state of the element. This function will try to set the -requested state by going through all the intermediary states and calling -the class's state change function for each. - -This function can return #GST_STATE_CHANGE_ASYNC, in which case the -element will perform the remainder of the state change asynchronously in -another thread. -An application can use gst_element_get_state() to wait for the completion -of the state change or it can wait for a %GST_MESSAGE_ASYNC_DONE or -%GST_MESSAGE_STATE_CHANGED on the bus. - -State changes to %GST_STATE_READY or %GST_STATE_NULL never return -#GST_STATE_CHANGE_ASYNC. - - - Result of the state change using #GstStateChangeReturn. - -MT safe. - - - - - a #GstElement to change state of. - - - - the element's new #GstState. - - - - - - Tries to change the state of the element to the same as its parent. -If this function returns %FALSE, the state of element is undefined. - - - %TRUE, if the element's state could be synced to the parent's state. - -MT safe. - - - - - a #GstElement. - - - - - - Unlinks all source pads of the source element with all sink pads -of the sink element to which they are linked. - -If the link has been made using gst_element_link(), it could have created an -requestpad, which has to be released using gst_element_release_request_pad(). - - - - - - - the source #GstElement to unlink. - - - - the sink #GstElement to unlink. - - - - - - Unlinks a series of elements. Uses gst_element_unlink(). - - - - - - - the first #GstElement in the link chain. - - - - the second #GstElement in the link chain. - - - - the %NULL-terminated list of elements to unlink in order. - - - - - - Unlinks the two named pads of the source and destination elements. - -This is a convenience function for gst_pad_unlink(). - - - - - - - a (transfer none): #GstElement containing the source pad. - - - - the name of the #GstPad in source element. - - - - a #GstElement containing the destination pad. - - - - the name of the #GstPad in destination element. - - - - - - - - - Used to serialize execution of gst_element_set_state() - - - - Used to signal completion of a state change - - - - Used to detect concurrent execution of -gst_element_set_state() and gst_element_get_state() - - - - the target state of an element as set by the application - - - - the current state of an element - - - - the next state of an element, can be #GST_STATE_VOID_PENDING if -the element is in the correct state. - - - - the final state the element should go to, can be -#GST_STATE_VOID_PENDING if the element is in the correct state - - - - the last return value of an element state change - - - - the bus of the element. This bus is provided to the element by the -parent element or the application. A #GstPipeline has a bus of its own. - - - - the clock of the element. This clock is usually provided to the -element by the toplevel #GstPipeline. - - - - the time of the clock right before the element is set to -PLAYING. Subtracting @base_time from the current clock time in the PLAYING -state will yield the running_time against the clock. - - - - the running_time of the last PAUSED state - - - - number of pads of the element, includes both source and sink pads. - - - - list of pads - - - - - - number of source pads of the element. - - - - list of source pads - - - - - - number of sink pads of the element. - - - - list of sink pads - - - - - - updated whenever the a pad is added or removed - - - - list of contexts - - - - - - - - - - - This signals that the element will not generate more dynamic pads. -Note that this signal will usually be emitted from the context of -the streaming thread. - - - - - - a new #GstPad has been added to the element. Note that this signal will -usually be emitted from the context of the streaming thread. Also keep in -mind that if you add new elements to the pipeline in the signal handler -you will need to set them to the desired target state with -gst_element_set_state() or gst_element_sync_state_with_parent(). - - - - - - the pad that has been added - - - - - - a #GstPad has been removed from the element - - - - - - the pad that has been removed - - - - - - - Callback prototype used in #gst_element_call_async - - - - - - - The #GstElement this function has been called against - - - - Data passed in the function where that callback has been passed - - - - - - GStreamer element class. Override the vmethods to implement the element -functionality. - - - the parent class structure - - - - metadata for elements of this class - - - - the #GstElementFactory that creates these elements - - - - a #GList of #GstPadTemplate - - - - - - the number of padtemplates - - - - changed whenever the padtemplates change - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstElement - - - - - - - - - - requested #GstPad if found, - otherwise %NULL. Release after usage. - - - - - a #GstElement to find a request pad of. - - - - a #GstPadTemplate of which we want a pad of. - - - - the name of the request #GstPad -to retrieve. Can be %NULL. - - - - the caps of the pad we want to -request. Can be %NULL. - - - - - - - - - - - - - - - - - - - - - - - - - - %GST_STATE_CHANGE_SUCCESS if the element has no more pending state - and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the - element is still performing a state change or - %GST_STATE_CHANGE_FAILURE if the last state change failed. - -MT safe. - - - - - a #GstElement to get the state of. - - - - a pointer to #GstState to hold the state. - Can be %NULL. - - - - a pointer to #GstState to hold the pending - state. Can be %NULL. - - - - a #GstClockTime to specify the timeout for an async - state change or %GST_CLOCK_TIME_NONE for infinite timeout. - - - - - - - - - - Result of the state change using #GstStateChangeReturn. - -MT safe. - - - - - a #GstElement to change state of. - - - - the element's new #GstState. - - - - - - - - - - the #GstStateChangeReturn of the state transition. - - - - - a #GstElement - - - - the requested transition - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstElement to set the bus of. - - - - the #GstBus to set. - - - - - - - - - - the GstClock provided by the -element or %NULL if no clock could be provided. Unref after usage. - -MT safe. - - - - - a #GstElement to query - - - - - - - - - - %TRUE if the element accepted the clock. An element can refuse a -clock when it, for example, is not able to slave its internal clock to the -@clock or when it requires a specific clock to operate. - -MT safe. - - - - - a #GstElement to set the clock for. - - - - the #GstClock to set for the element. - - - - - - - - - - %TRUE if the event was handled. Events that trigger a preroll (such -as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. - - - - - a #GstElement to send the event to. - - - - the #GstEvent to send to the element. - - - - - - - - - - %TRUE if the query could be performed. - -MT safe. - - - - - a #GstElement to perform the query on. - - - - the #GstQuery. - - - - - - - - - - %TRUE if the message was successfully posted. The function returns -%FALSE if the element did not have a bus. - -MT safe. - - - - - a #GstElement posting the message - - - - a #GstMessage to post - - - - - - - - - - - - - - a #GstElement to set the context of. - - - - the #GstContext to set. - - - - - - - - - - - - Set @key with @value as metadata in @klass. - - - - - - - class to set metadata for - - - - the key to set - - - - the value to set - - - - - - Adds a padtemplate to an element class. This is mainly used in the _class_init -functions of classes. If a pad template with the same name as an already -existing one is added the old one is replaced by the new one. - -@templ's reference count will be incremented, and any floating -reference will be removed (see gst_object_ref_sink()) - - - - - - - the #GstElementClass to add the pad template to. - - - - a #GstPadTemplate to add to the element class. - - - - - - Set @key with @value as metadata in @klass. - -Same as gst_element_class_add_metadata(), but @value must be a static string -or an inlined string, as it will not be copied. (GStreamer plugins will -be made resident once loaded, so this function can be used even from -dynamically loaded plugins.) - - - - - - - class to set metadata for - - - - the key to set - - - - the value to set - - - - - - Adds a pad template to an element class based on the static pad template -@templ. This is mainly used in the _class_init functions of element -implementations. If a pad template with the same name already exists, -the old one is replaced by the new one. - - - - - - - the #GstElementClass to add the pad template to. - - - - #GstStaticPadTemplate to add as pad template to the element class. - - - - - - Adds a pad template to an element class based on the static pad template -@templ. This is mainly used in the _class_init functions of element -implementations. If a pad template with the same name already exists, -the old one is replaced by the new one. - - - - - - - the #GstElementClass to add the pad template to. - - - - #GstStaticPadTemplate to add as pad template to the element class. - - - - The #GType of the pad to create - - - - - - Get metadata with @key in @klass. - - - the metadata for @key. - - - - - class to get metadata for - - - - the key to get - - - - - - Retrieves a padtemplate from @element_class with the given name. -> If you use this function in the #GInstanceInitFunc of an object class -> that has subclasses, make sure to pass the g_class parameter of the -> #GInstanceInitFunc here. - - - the #GstPadTemplate with the - given name, or %NULL if none was found. No unreferencing is - necessary. - - - - - a #GstElementClass to get the pad template of. - - - - the name of the #GstPadTemplate to get. - - - - - - Retrieves a list of the pad templates associated with @element_class. The -list must not be modified by the calling code. -> If you use this function in the #GInstanceInitFunc of an object class -> that has subclasses, make sure to pass the g_class parameter of the -> #GInstanceInitFunc here. - - - the #GList of - pad templates. - - - - - - - a #GstElementClass to get pad templates of. - - - - - - Sets the detailed information for a #GstElementClass. -> This function is for use in _class_init functions only. - - - - - - - class to set metadata for - - - - The long English name of the element. E.g. "File Sink" - - - - String describing the type of element, as an unordered list -separated with slashes ('/'). See draft-klass.txt of the design docs -for more details and common types. E.g: "Sink/File" - - - - Sentence describing the purpose of the element. -E.g: "Write stream to a file" - - - - Name and contact details of the author(s). Use \n to separate -multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" - - - - - - Sets the detailed information for a #GstElementClass. - -> This function is for use in _class_init functions only. - -Same as gst_element_class_set_metadata(), but @longname, @classification, -@description, and @author must be static strings or inlined strings, as -they will not be copied. (GStreamer plugins will be made resident once -loaded, so this function can be used even from dynamically loaded plugins.) - - - - - - - class to set metadata for - - - - The long English name of the element. E.g. "File Sink" - - - - String describing the type of element, as an unordered list -separated with slashes ('/'). See draft-klass.txt of the design docs -for more details and common types. E.g: "Sink/File" - - - - Sentence describing the purpose of the element. -E.g: "Write stream to a file" - - - - Name and contact details of the author(s). Use \n to separate -multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" - - - - - - - #GstElementFactory is used to create instances of elements. A -GstElementFactory can be added to a #GstPlugin as it is also a -#GstPluginFeature. - -Use the gst_element_factory_find() and gst_element_factory_create() -functions to create element instances or use gst_element_factory_make() as a -convenient shortcut. - -The following code example shows you how to create a GstFileSrc element. - -## Using an element factory -|[<!-- language="C" --> - #include &lt;gst/gst.h&gt; - - GstElement *src; - GstElementFactory *srcfactory; - - gst_init (&amp;argc, &amp;argv); - - srcfactory = gst_element_factory_find ("filesrc"); - g_return_if_fail (srcfactory != NULL); - src = gst_element_factory_create (srcfactory, "src"); - g_return_if_fail (src != NULL); - ... -]| - - - Search for an element factory of the given name. Refs the returned -element factory; caller is responsible for unreffing. - - - #GstElementFactory if found, -%NULL otherwise - - - - - name of factory to find - - - - - - Filter out all the elementfactories in @list that can handle @caps in -the given direction. - -If @subsetonly is %TRUE, then only the elements whose pads templates -are a complete superset of @caps will be returned. Else any element -whose pad templates caps can intersect with @caps will be returned. - - - a #GList of - #GstElementFactory elements that match the given requisites. - Use #gst_plugin_feature_list_free after usage. - - - - - - - a #GList of - #GstElementFactory to filter - - - - - - a #GstCaps - - - - a #GstPadDirection to filter on - - - - whether to filter on caps subsets or not. - - - - - - Get a list of factories that match the given @type. Only elements -with a rank greater or equal to @minrank will be returned. -The list of factories is returned by decreasing rank. - - - a #GList of - #GstElementFactory elements. Use gst_plugin_feature_list_free() after - usage. - - - - - - - a #GstElementFactoryListType - - - - Minimum rank - - - - - - Create a new element of the type defined by the given element factory. -If name is %NULL, then the element will receive a guaranteed unique name, -consisting of the element factory name and a number. -If name is given, it will be given the name supplied. - - - new #GstElement or %NULL -if unable to create element - - - - - a named factory to instantiate - - - - name of new element, or %NULL to automatically create - a unique name - - - - - - Checks if the factory can sink all possible capabilities. - - - %TRUE if the caps are fully compatible. - - - - - factory to query - - - - the caps to check - - - - - - Checks if the factory can sink any possible capability. - - - %TRUE if the caps have a common subset. - - - - - factory to query - - - - the caps to check - - - - - - Checks if the factory can src all possible capabilities. - - - %TRUE if the caps are fully compatible. - - - - - factory to query - - - - the caps to check - - - - - - Checks if the factory can src any possible capability. - - - %TRUE if the caps have a common subset. - - - - - factory to query - - - - the caps to check - - - - - - Create a new element of the type defined by the given elementfactory. -It will be given the name supplied, since all elements require a name as -their first argument. - - - new #GstElement or %NULL - if the element couldn't be created - - - - - factory to instantiate - - - - name of new element, or %NULL to automatically create - a unique name - - - - - - Get the #GType for elements managed by this factory. The type can -only be retrieved if the element factory is loaded, which can be -assured with gst_plugin_feature_load(). - - - the #GType for elements managed by this factory or 0 if -the factory is not loaded. - - - - - factory to get managed #GType from - - - - - - Get the metadata on @factory with @key. - - - the metadata with @key on @factory or %NULL -when there was no metadata with the given @key. - - - - - a #GstElementFactory - - - - a key - - - - - - Get the available keys for the metadata on @factory. - - - -a %NULL-terminated array of key strings, or %NULL when there is no -metadata. Free with g_strfreev() when no longer needed. - - - - - - - a #GstElementFactory - - - - - - Gets the number of pad_templates in this factory. - - - the number of pad_templates - - - - - a #GstElementFactory - - - - - - Gets the #GList of #GstStaticPadTemplate for this factory. - - - the - static pad templates - - - - - - - a #GstElementFactory - - - - - - Gets a %NULL-terminated array of protocols this element supports or %NULL if -no protocols are supported. You may not change the contents of the returned -array, as it is still owned by the element factory. Use g_strdupv() to -make a copy of the protocol string array if you need to. - - - the supported protocols - or %NULL - - - - - - - a #GstElementFactory - - - - - - Gets the type of URIs the element supports or #GST_URI_UNKNOWN if none. - - - type of URIs this element supports - - - - - a #GstElementFactory - - - - - - Check if @factory implements the interface with name @interfacename. - - - %TRUE when @factory implement the interface. - - - - - a #GstElementFactory - - - - an interface name - - - - - - Check if @factory is of the given types. - - - %TRUE if @factory is of @type. - - - - - a #GstElementFactory - - - - a #GstElementFactoryListType - - - - - - - - - - The standard flags that an element may have. - - ignore state changes from parent - - - the element is a sink - - - the element is a source. - - - the element can provide a clock - - - the element requires a clock - - - the element can use an index - - - offset to define more flags - - - - Function called for each pad when using gst_element_foreach_sink_pad(), -gst_element_foreach_src_pad(), or gst_element_foreach_pad(). - - - %FALSE to stop iterating pads, %TRUE to continue - - - - - the #GstElement - - - - a #GstPad - - - - user data passed to the foreach function - - - - - - The event class provides factory methods to construct events for sending -and functions to query (parse) received events. - -Events are usually created with gst_event_new_*() which takes event-type -specific parameters as arguments. -To send an event application will usually use gst_element_send_event() and -elements will use gst_pad_send_event() or gst_pad_push_event(). -The event should be unreffed with gst_event_unref() if it has not been sent. - -Events that have been received can be parsed with their respective -gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details. - -Events are passed between elements in parallel to the data stream. Some events -are serialized with buffers, others are not. Some events only travel downstream, -others only upstream. Some events can travel both upstream and downstream. - -The events are used to signal special conditions in the datastream such as -EOS (end of stream) or the start of a new stream-segment. -Events are also used to flush the pipeline of any pending data. - -Most of the event API is used inside plugins. Applications usually only -construct and use seek events. -To do that gst_event_new_seek() is used to create a seek event. It takes -the needed parameters to specify seeking time and mode. -|[<!-- language="C" --> - GstEvent *event; - gboolean result; - ... - // construct a seek event to play the media from second 2 to 5, flush - // the pipeline to decrease latency. - event = gst_event_new_seek (1.0, - GST_FORMAT_TIME, - GST_SEEK_FLAG_FLUSH, - GST_SEEK_TYPE_SET, 2 * GST_SECOND, - GST_SEEK_TYPE_SET, 5 * GST_SECOND); - ... - result = gst_element_send_event (pipeline, event); - if (!result) - g_warning ("seek failed"); - ... -]| - - - the parent structure - - - - the #GstEventType of the event - - - - the timestamp of the event - - - - the sequence number of the event - - - - Create a new buffersize event. The event is sent downstream and notifies -elements that they should provide a buffer of the specified dimensions. - -When the @async flag is set, a thread boundary is preferred. - - - a new #GstEvent - - - - - buffer format - - - - minimum buffer size - - - - maximum buffer size - - - - thread behavior - - - - - - Create a new CAPS event for @caps. The caps event can only travel downstream -synchronized with the buffer flow and contains the format of the buffers -that will follow after the event. - - - the new CAPS event. - - - - - a #GstCaps - - - - - - Create a new custom-typed event. This can be used for anything not -handled by other event-specific functions to pass an event to another -element. - -Make sure to allocate an event type with the #GST_EVENT_MAKE_TYPE macro, -assigning a free number and filling in the correct direction and -serialization flags. - -New custom events can also be created by subclassing the event type if -needed. - - - the new custom event. - - - - - The type of the new event - - - - the structure for the event. The event will - take ownership of the structure. - - - - - - Create a new EOS event. The eos event can only travel downstream -synchronized with the buffer flow. Elements that receive the EOS -event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn -when data after the EOS event arrives. - -The EOS event will travel down to the sink elements in the pipeline -which will then post the #GST_MESSAGE_EOS on the bus after they have -finished playing any buffered data. - -When all sinks have posted an EOS message, an EOS message is -forwarded to the application. - -The EOS event itself will not cause any state transitions of the pipeline. - - - the new EOS event. - - - - - Allocate a new flush start event. The flush start event can be sent -upstream and downstream and travels out-of-bounds with the dataflow. - -It marks pads as being flushing and will make them return -#GST_FLOW_FLUSHING when used for data flow with gst_pad_push(), -gst_pad_chain(), gst_pad_get_range() and gst_pad_pull_range(). -Any event (except a #GST_EVENT_FLUSH_STOP) received -on a flushing pad will return %FALSE immediately. - -Elements should unlock any blocking functions and exit their streaming -functions as fast as possible when this event is received. - -This event is typically generated after a seek to flush out all queued data -in the pipeline so that the new media is played as soon as possible. - - - a new flush start event. - - - - - Allocate a new flush stop event. The flush stop event can be sent -upstream and downstream and travels serialized with the dataflow. -It is typically sent after sending a FLUSH_START event to make the -pads accept data again. - -Elements can process this event synchronized with the dataflow since -the preceding FLUSH_START event stopped the dataflow. - -This event is typically generated to complete a seek and to resume -dataflow. - - - a new flush stop event. - - - - - if time should be reset - - - - - - Create a new GAP event. A gap event can be thought of as conceptually -equivalent to a buffer to signal that there is no data for a certain -amount of time. This is useful to signal a gap to downstream elements -which may wait for data, such as muxers or mixers or overlays, especially -for sparse streams such as subtitle streams. - - - the new GAP event. - - - - - the start time (pts) of the gap - - - - the duration of the gap - - - - - - Create a new instant-rate-change event. This event is sent by seek -handlers (e.g. demuxers) when receiving a seek with the -%GST_SEEK_FLAG_INSTANT_RATE_CHANGE and signals to downstream elements that -the playback rate in the existing segment should be immediately multiplied -by the @rate_multiplier factor. - -The flags provided replace any flags in the existing segment, for the -flags within the %GST_SEGMENT_INSTANT_FLAGS set. Other GstSegmentFlags -are ignored and not transferred in the event. - - - the new instant-rate-change event. - - - - - the multiplier to be applied to the playback rate - - - - A new subset of segment flags to replace in segments - - - - - - Create a new instant-rate-sync-time event. This event is sent by the -pipeline to notify elements handling the instant-rate-change event about -the running-time when the new rate should be applied. The running time -may be in the past when elements handle this event, which can lead to -switching artifacts. The magnitude of those depends on the exact timing -of event delivery to each element and the magnitude of the change in -playback rate being applied. - -The @running_time and @upstream_running_time are the same if this -is the first instant-rate adjustment, but will differ for later ones -to compensate for the accumulated offset due to playing at a rate -different to the one indicated in the playback segments. - - - the new instant-rate-sync-time event. - - - - - the new playback rate multiplier to be applied - - - - Running time when the rate change should be applied - - - - The upstream-centric running-time when the - rate change should be applied. - - - - - - Create a new latency event. The event is sent upstream from the sinks and -notifies elements that they should add an additional @latency to the -running time before synchronising against the clock. - -The latency is mostly used in live sinks and is always expressed in -the time format. - - - a new #GstEvent - - - - - the new latency value - - - - - - Create a new navigation event from the given description. - - - a new #GstEvent - - - - - description of the event. The event will take - ownership of the structure. - - - - - - Creates a new event containing information specific to a particular -protection system (uniquely identified by @system_id), by which that -protection system can acquire key(s) to decrypt a protected stream. - -In order for a decryption element to decrypt media -protected using a specific system, it first needs all the -protection system specific information necessary to acquire the decryption -key(s) for that stream. The functions defined here enable this information -to be passed in events from elements that extract it -(e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter -elements that use it. - -Events containing protection system specific information are created using -#gst_event_new_protection, and they can be parsed by downstream elements -using #gst_event_parse_protection. - -In Common Encryption, protection system specific information may be located -within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) -boxes; it may also be contained in ContentProtection elements within MPEG -DASH MPDs. The events created by #gst_event_new_protection contain data -identifying from which of these locations the encapsulated protection system -specific information originated. This origin information is required as -some protection systems use different encodings depending upon where the -information originates. - -The events returned by gst_event_new_protection() are implemented -in such a way as to ensure that the most recently-pushed protection info -event of a particular @origin and @system_id will -be stuck to the output pad of the sending element. - - - a #GST_EVENT_PROTECTION event, if successful; %NULL -if unsuccessful. - - - - - a string holding a UUID that uniquely -identifies a protection system. - - - - a #GstBuffer holding protection system specific -information. The reference count of the buffer will be incremented by one. - - - - a string indicating where the protection -information carried in the event was extracted from. The allowed values -of this string will depend upon the protection scheme. - - - - - - Allocate a new qos event with the given values. -The QOS event is generated in an element that wants an upstream -element to either reduce or increase its rate because of -high/low CPU load or other resource usage such as network performance or -throttling. Typically sinks generate these events for each buffer -they receive. - -@type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is -used when a buffer arrived in time or when the sink cannot keep up with -the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not -receiving buffers fast enough and thus has to drop late buffers. -#GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited -by the application, for example to reduce power consumption. - -@proportion indicates the real-time performance of the streaming in the -element that generated the QoS event (usually the sink). The value is -generally computed based on more long term statistics about the streams -timestamps compared to the clock. -A value < 1.0 indicates that the upstream element is producing data faster -than real-time. A value > 1.0 indicates that the upstream element is not -producing data fast enough. 1.0 is the ideal @proportion value. The -proportion value can safely be used to lower or increase the quality of -the element. - -@diff is the difference against the clock in running time of the last -buffer that caused the element to generate the QOS event. A negative value -means that the buffer with @timestamp arrived in time. A positive value -indicates how late the buffer with @timestamp was. When throttling is -enabled, @diff will be set to the requested throttling interval. - -@timestamp is the timestamp of the last buffer that cause the element -to generate the QOS event. It is expressed in running time and thus an ever -increasing value. - -The upstream element can use the @diff and @timestamp values to decide -whether to process more buffers. For positive @diff, all buffers with -timestamp <= @timestamp + @diff will certainly arrive late in the sink -as well. A (negative) @diff value so that @timestamp + @diff would yield a -result smaller than 0 is not allowed. - -The application can use general event probes to intercept the QoS -event and implement custom application specific QoS handling. - - - a new QOS event. - - - - - the QoS type - - - - the proportion of the qos message - - - - The time difference of the last Clock sync - - - - The timestamp of the buffer - - - - - - Create a new reconfigure event. The purpose of the reconfigure event is -to travel upstream and make elements renegotiate their caps or reconfigure -their buffer pools. This is useful when changing properties on elements -or changing the topology of the pipeline. - - - a new #GstEvent - - - - - Allocate a new seek event with the given parameters. - -The seek event configures playback of the pipeline between @start to @stop -at the speed given in @rate, also called a playback segment. -The @start and @stop values are expressed in @format. - -A @rate of 1.0 means normal playback rate, 2.0 means double speed. -Negatives values means backwards playback. A value of 0.0 for the -rate is not allowed and should be accomplished instead by PAUSING the -pipeline. - -A pipeline has a default playback segment configured with a start -position of 0, a stop position of -1 and a rate of 1.0. The currently -configured playback segment can be queried with #GST_QUERY_SEGMENT. - -@start_type and @stop_type specify how to adjust the currently configured -start and stop fields in playback segment. Adjustments can be made relative -or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE -means that the position should not be updated. - -When the rate is positive and @start has been updated, playback will start -from the newly configured start position. - -For negative rates, playback will start from the newly configured stop -position (if any). If the stop position is updated, it must be different from --1 (#GST_CLOCK_TIME_NONE) for negative rates. - -It is not possible to seek relative to the current playback position, to do -this, PAUSE the pipeline, query the current playback position with -#GST_QUERY_POSITION and update the playback segment current position with a -#GST_SEEK_TYPE_SET to the desired position. - - - a new seek event. - - - - - The new playback rate - - - - The format of the seek values - - - - The optional seek flags - - - - The type and flags for the new start position - - - - The value of the new start position - - - - The type and flags for the new stop position - - - - The value of the new stop position - - - - - - Create a new SEGMENT event for @segment. The segment event can only travel -downstream synchronized with the buffer flow and contains timing information -and playback properties for the buffers that will follow. - -The segment event marks the range of buffers to be processed. All -data not within the segment range is not to be processed. This can be -used intelligently by plugins to apply more efficient methods of skipping -unneeded data. The valid range is expressed with the @start and @stop -values. - -The time value of the segment is used in conjunction with the start -value to convert the buffer timestamps into the stream time. This is -usually done in sinks to report the current stream_time. -@time represents the stream_time of a buffer carrying a timestamp of -@start. @time cannot be -1. - -@start cannot be -1, @stop can be -1. If there -is a valid @stop given, it must be greater or equal the @start, including -when the indicated playback @rate is < 0. - -The @applied_rate value provides information about any rate adjustment that -has already been made to the timestamps and content on the buffers of the -stream. (@rate * @applied_rate) should always equal the rate that has been -requested for playback. For example, if an element has an input segment -with intended playback @rate of 2.0 and applied_rate of 1.0, it can adjust -incoming timestamps and buffer content by half and output a segment event -with @rate of 1.0 and @applied_rate of 2.0 - -After a segment event, the buffer stream time is calculated with: - - time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) - - - the new SEGMENT event. - - - - - a #GstSegment - - - - - - Create a new segment-done event. This event is sent by elements that -finish playback of a segment as a result of a segment seek. - - - a new #GstEvent - - - - - The format of the position being done - - - - The position of the segment being done - - - - - - Allocate a new select-streams event. - -The select-streams event requests the specified @streams to be activated. - -The list of @streams corresponds to the "Stream ID" of each stream to be -activated. Those ID can be obtained via the #GstStream objects present -in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or -#GST_MESSAGE_STREAM_COLLECTION. - -Note: The list of @streams can not be empty. - - - a new select-streams event or %NULL in case of -an error (like an empty streams list). - - - - - the list of streams to -activate - - - - - - - - Create a new sink-message event. The purpose of the sink-message event is -to instruct a sink to post the message contained in the event synchronized -with the stream. - -@name is used to store multiple sticky events on one pad. - - - a new #GstEvent - - - - - a name for the event - - - - the #GstMessage to be posted - - - - - - Create a new step event. The purpose of the step event is to instruct a sink -to skip @amount (expressed in @format) of media. It can be used to implement -stepping through the video frame by frame or for doing fast trick modes. - -A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate -= 0.0 or first reverse the direction of playback using a seek event to get -the same effect as rate < 0.0. - -The @flush flag will clear any pending data in the pipeline before starting -the step operation. - -The @intermediate flag instructs the pipeline that this step operation is -part of a larger step operation. - - - a new #GstEvent - - - - - the format of @amount - - - - the amount of data to step - - - - the step rate - - - - flushing steps - - - - intermediate steps - - - - - - Create a new STREAM_COLLECTION event. The stream collection event can only -travel downstream synchronized with the buffer flow. - -Source elements, demuxers and other elements that manage collections -of streams and post #GstStreamCollection messages on the bus also send -this event downstream on each pad involved in the collection, so that -activation of a new collection can be tracked through the downstream -data flow. - - - the new STREAM_COLLECTION event. - - - - - Active collection for this data flow - - - - - - Create a new Stream Group Done event. The stream-group-done event can -only travel downstream synchronized with the buffer flow. Elements -that receive the event on a pad should handle it mostly like EOS, -and emit any data or pending buffers that would depend on more data -arriving and unblock, since there won't be any more data. - -This event is followed by EOS at some point in the future, and is -generally used when switching pads - to unblock downstream so that -new pads can be exposed before sending EOS on the existing pads. - - - the new stream-group-done event. - - - - - the group id of the stream group which is ending - - - - - - Create a new STREAM_START event. The stream start event can only -travel downstream synchronized with the buffer flow. It is expected -to be the first event that is sent for a new stream. - -Source elements, demuxers and other elements that create new streams -are supposed to send this event as the first event of a new stream. It -should not be sent after a flushing seek or in similar situations -and is used to mark the beginning of a new logical stream. Elements -combining multiple streams must ensure that this event is only forwarded -downstream once and not for every single input stream. - -The @stream_id should be a unique string that consists of the upstream -stream-id, / as separator and a unique stream-id for this specific -stream. A new stream-id should only be created for a stream if the upstream -stream is split into (potentially) multiple new streams, e.g. in a demuxer, -but not for every single element in the pipeline. -gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be -used to create a stream-id. There are no particular semantics for the -stream-id, though it should be deterministic (to support stream matching) -and it might be used to order streams (besides any information conveyed by -stream flags). - - - the new STREAM_START event. - - - - - Identifier for this stream - - - - - - Generates a metadata tag event from the given @taglist. - -The scope of the taglist specifies if the taglist applies to the -complete medium or only to this specific stream. As the tag event -is a sticky event, elements should merge tags received from -upstream with a given scope with their own tags with the same -scope and create a new tag event from it. - - - a new #GstEvent - - - - - metadata list. The event will take ownership - of the taglist. - - - - - - Generate a TOC event from the given @toc. The purpose of the TOC event is to -inform elements that some kind of the TOC was found. - - - a new #GstEvent. - - - - - #GstToc structure. - - - - whether @toc was updated or not. - - - - - - Generate a TOC select event with the given @uid. The purpose of the -TOC select event is to start playback based on the TOC's entry with the -given @uid. - - - a new #GstEvent. - - - - - UID in the TOC to start playback from. - - - - - - Copy the event using the event specific copy function. - - - the new event - - - - - The event to copy - - - - - - Parses a segment @event and copies the #GstSegment into the location -given by @segment. - - - - - - - The event to parse - - - - a pointer to a #GstSegment - - - - - - Retrieve the accumulated running time offset of the event. - -Events passing through #GstPads that have a running time -offset set via gst_pad_set_offset() will get their offset -adjusted according to the pad's offset. - -If the event contains any information that related to the -running time, this information will need to be updated -before usage with this offset. - - - The event's running time offset - -MT safe. - - - - - A #GstEvent. - - - - - - Retrieve the sequence number of a event. - -Events have ever-incrementing sequence numbers, which may also be set -explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to -indicate that a event corresponds to some other set of events or messages, -for example an EOS event 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. - - - The event's sequence number. - -MT safe. - - - - - A #GstEvent. - - - - - - Access the structure of the event. - - - The structure of the event. The -structure is still owned by the event, which means that you should not free -it and that the pointer becomes invalid when you free the event. - -MT safe. - - - - - The #GstEvent. - - - - - - Checks if @event has the given @name. This function is usually used to -check the name of a custom event. - - - %TRUE if @name matches the name of the event structure. - - - - - The #GstEvent. - - - - name to check - - - - - - Checks if @event has the given @name. This function is usually used to -check the name of a custom event. - - - %TRUE if @name matches the name of the event structure. - - - - - The #GstEvent. - - - - name to check as a GQuark - - - - - - Get the format, minsize, maxsize and async-flag in the buffersize event. - - - - - - - The event to query - - - - A pointer to store the format in - - - - A pointer to store the minsize in - - - - A pointer to store the maxsize in - - - - A pointer to store the async-flag in - - - - - - Get the caps from @event. The caps remains valid as long as @event remains -valid. - - - - - - - The event to parse - - - - A pointer to the caps - - - - - - Parse the FLUSH_STOP event and retrieve the @reset_time member. - - - - - - - The event to parse - - - - if time should be reset - - - - - - Extract timestamp and duration from a new GAP event. - - - - - - - a #GstEvent of type #GST_EVENT_GAP - - - - location where to store the - start time (pts) of the gap, or %NULL - - - - location where to store the duration of - the gap, or %NULL - - - - - - - - %TRUE if a group id was set on the event and could be parsed, - %FALSE otherwise. - - - - - a stream-start event - - - - address of variable where to store the group id - - - - - - Extract rate and flags from an instant-rate-change event. - - - - - - - a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE - - - - location in which to store the rate - multiplier of the instant-rate-change event, or %NULL - - - - location in which to store the new - segment flags of the instant-rate-change event, or %NULL - - - - - - Extract the rate multiplier and running times from an instant-rate-sync-time event. - - - - - - - a #GstEvent of type #GST_EVENT_INSTANT_RATE_CHANGE - - - - location where to store the rate of - the instant-rate-sync-time event, or %NULL - - - - location in which to store the running time - of the instant-rate-sync-time event, or %NULL - - - - location in which to store the - upstream running time of the instant-rate-sync-time event, or %NULL - - - - - - Get the latency in the latency event. - - - - - - - The event to query - - - - A pointer to store the latency in. - - - - - - Parses an event containing protection system specific information and stores -the results in @system_id, @data and @origin. The data stored in @system_id, -@origin and @data are valid until @event is released. - - - - - - - a #GST_EVENT_PROTECTION event. - - - - pointer to store the UUID -string uniquely identifying a content protection system. - - - - pointer to store a #GstBuffer -holding protection system specific information. - - - - pointer to store a value that -indicates where the protection information carried by @event was extracted -from. - - - - - - Get the type, proportion, diff and timestamp in the qos event. See -gst_event_new_qos() for more information about the different QoS values. - -@timestamp will be adjusted for any pad offsets of pads it was passing through. - - - - - - - The event to query - - - - A pointer to store the QoS type in - - - - A pointer to store the proportion in - - - - A pointer to store the diff in - - - - A pointer to store the timestamp in - - - - - - Parses a seek @event and stores the results in the given result locations. - - - - - - - a seek event - - - - result location for the rate - - - - result location for the stream format - - - - result location for the #GstSeekFlags - - - - result location for the #GstSeekType of the start position - - - - result location for the start position expressed in @format - - - - result location for the #GstSeekType of the stop position - - - - result location for the stop position expressed in @format - - - - - - Retrieve the trickmode interval that may have been set on a -seek event with gst_event_set_seek_trickmode_interval(). - - - - - - - - - - - - - - - Parses a segment @event and stores the result in the given @segment location. -@segment remains valid only until the @event is freed. Don't modify the segment -and make a copy if you want to modify it or store it for later use. - - - - - - - The event to parse - - - - a pointer to a #GstSegment - - - - - - Extracts the position and format from the segment done message. - - - - - - - A valid #GstEvent of type GST_EVENT_SEGMENT_DONE. - - - - Result location for the format, or %NULL - - - - Result location for the position, or %NULL - - - - - - Parse the SELECT_STREAMS event and retrieve the contained streams. - - - - - - - The event to parse - - - - the streams - - - - - - - - Parse the sink-message event. Unref @msg after usage. - - - - - - - The event to query - - - - a pointer to store the #GstMessage in. - - - - - - Parse the step event. - - - - - - - The event to query - - - - a pointer to store the format in - - - - a pointer to store the amount in - - - - a pointer to store the rate in - - - - a pointer to store the flush boolean in - - - - a pointer to store the intermediate - boolean in - - - - - - Parse a stream-start @event and extract the #GstStream from it. - - - - - - - a stream-start event - - - - address of variable to store the stream - - - - - - Retrieve new #GstStreamCollection from STREAM_COLLECTION event @event. - - - - - - - a stream-collection event - - - - pointer to store the collection - - - - - - - - - - - - a stream-start event - - - - address of variable where to store the stream flags - - - - - - Parse a stream-group-done @event and store the result in the given -@group_id location. - - - - - - - a stream-group-done event. - - - - address of variable to store the group id into - - - - - - Parse a stream-id @event and store the result in the given @stream_id -location. The string stored in @stream_id must not be modified and will -remain valid only until @event gets freed. Make a copy if you want to -modify it or store it for later use. - - - - - - - a stream-start event. - - - - pointer to store the stream-id - - - - - - Parses a tag @event and stores the results in the given @taglist location. -No reference to the taglist will be returned, it remains valid only until -the @event is freed. Don't modify or free the taglist, make a copy if you -want to modify it or store it for later use. - - - - - - - a tag event - - - - pointer to metadata list - - - - - - Parse a TOC @event and store the results in the given @toc and @updated locations. - - - - - - - a TOC event. - - - - pointer to #GstToc structure. - - - - pointer to store TOC updated flag. - - - - - - Parse a TOC select @event and store the results in the given @uid location. - - - - - - - a TOC select event. - - - - storage for the selection UID. - - - - - - Increase the refcount of this event. - - - @event (for convenience when doing assignments) - - - - - The event to refcount - - - - - - 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. - -Use gst_util_group_id_next() to get a new group id. - - - - - - - a stream-start event - - - - the group id to set - - - - - - Set the running time offset of a event. See -gst_event_get_running_time_offset() for more information. - -MT safe. - - - - - - - A #GstEvent. - - - - A the new running time offset - - - - - - Sets a trickmode interval on a (writable) seek event. Elements -that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal -interval between each frame they may output. - - - - - - - - - - - - - - - Set the sequence number of a event. - -This function might be called by the creator of a event to indicate that the -event relates to other events or messages. See gst_event_get_seqnum() for -more information. - -MT safe. - - - - - - - A #GstEvent. - - - - A sequence number. - - - - - - Set the @stream on the stream-start @event - - - - - - - a stream-start event - - - - the stream object to set - - - - - - - - - - - - a stream-start event - - - - the stream flags to set - - - - - - Decrease the refcount of an event, freeing it if the refcount reaches 0. - - - - - - - the event to refcount - - - - - - Get a writable version of the structure. - - - The structure of the event. The structure -is still owned by the event, which means that you should not free -it and that the pointer becomes invalid when you free the event. -This function checks if @event is writable and will never return -%NULL. - -MT safe. - - - - - The #GstEvent. - - - - - - Modifies a pointer to a #GstEvent to point to a different #GstEvent. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -event is unreffed, the new one is reffed). - -Either @new_event or the #GstEvent pointed to by @old_event may be %NULL. - - - %TRUE if @new_event was different from @old_event - - - - - pointer to a - pointer to a #GstEvent to be replaced. - - - - pointer to a #GstEvent that will - replace the event pointed to by @old_event. - - - - - - Atomically replace the #GstEvent pointed to by @old_event with %NULL and -return the original event. - - - the #GstEvent that was in @old_event - - - - - pointer to a - pointer to a #GstEvent to be stolen. - - - - - - Modifies a pointer to a #GstEvent to point to a different #GstEvent. This -function is similar to gst_event_replace() except that it takes ownership of -@new_event. - -Either @new_event or the #GstEvent pointed to by @old_event may be %NULL. - - - %TRUE if @new_event was different from @old_event - - - - - pointer to a - pointer to a #GstEvent to be stolen. - - - - pointer to a #GstEvent that will - replace the event pointed to by @old_event. - - - - - - - #GstEventType lists the standard event types that can be sent in a pipeline. - -The custom event types can be used for private messages between elements -that can't be expressed using normal -GStreamer buffer passing semantics. Custom events carry an arbitrary -#GstStructure. -Specific custom events are distinguished by the name of the structure. - - unknown event. - - - Start a flush operation. This event clears all data - from the pipeline and unblock all streaming threads. - - - Stop a flush operation. This event resets the - running-time of the pipeline. - - - Event to mark the start of a new stream. Sent before any - other serialized event and only sent at the start of a new stream, - not after flushing seeks. - - - #GstCaps event. Notify the pad of a new media type. - - - A new media segment follows in the dataflow. The - segment events contains information for clipping buffers and - converting buffer timestamps to running-time and - stream-time. - - - A new #GstStreamCollection is available (Since: 1.10) - - - A new set of metadata tags has been found in the stream. - - - Notification of buffering requirements. Currently not - used yet. - - - An event that sinks turn into a message. Used to - send messages that should be emitted in sync with - rendering. - - - Indicates that there is no more data for - the stream group ID in the message. Sent before EOS - in some instances and should be handled mostly the same. (Since: 1.10) - - - End-Of-Stream. No more data is to be expected to follow - without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT - event. - - - An event which indicates that a new table of contents (TOC) - was found or updated. - - - An event which indicates that new or updated - encryption information has been found in the stream. - - - Marks the end of a segment playback. - - - Marks a gap in the datastream. - - - Notify downstream that a playback rate override - should be applied as soon as possible. (Since: 1.18) - - - A quality message. Used to indicate to upstream elements - that the downstream elements should adjust their processing - rate. - - - A request for a new playback position and rate. - - - Navigation events are usually used for communicating - user requests, such as mouse or keyboard movements, - to upstream elements. - - - Notification of new latency adjustment. Sinks will use - the latency information to adjust their synchronisation. - - - A request for stepping through the media. Sinks will usually - execute the step operation. - - - A request for upstream renegotiating caps and reconfiguring. - - - A request for a new playback position based on TOC - entry's UID. - - - A request to select one or more streams (Since: 1.10) - - - Sent by the pipeline to notify elements that handle the - instant-rate-change event about the running-time when - the rate multiplier should be applied (or was applied). (Since: 1.18) - - - Upstream custom event - - - Downstream custom event that travels in the - data flow. - - - Custom out-of-band downstream event. - - - Custom sticky downstream event. - - - Custom upstream or downstream event. - In-band when travelling downstream. - - - Custom upstream or downstream out-of-band event. - - - Gets the #GstEventTypeFlags associated with @type. - - - a #GstEventTypeFlags. - - - - - a #GstEventType - - - - - - Get a printable name for the given event type. Do not modify or free. - - - a reference to the static name of the event. - - - - - the event type - - - - - - Get the unique quark for the given event type. - - - the quark associated with the event type - - - - - the event type - - - - - - - #GstEventTypeFlags indicate the aspects of the different #GstEventType -values. You can get the type flags of a #GstEventType with the -gst_event_type_get_flags() function. - - Set if the event can travel upstream. - - - Set if the event can travel downstream. - - - Set if the event should be serialized with data - flow. - - - Set if the event is sticky on the pads. - - - Multiple sticky events can be on a pad, each - identified by the event name. - - - - A mask value with all bits set, for use as a -GstFlagSet mask where all flag bits must match -exactly - - - - - The PERCENT format is between 0 and this value - - - - - The value used to scale down the reported PERCENT format value to -its real value. - - - - - Can be used together with #GST_FOURCC_FORMAT to properly output a -#guint32 fourcc value in a printf\()-style text message. - - - - a #guint32 fourcc value to output - - - - - Can be used together with #GST_FOURCC_ARGS to properly output a -#guint32 fourcc value in a printf\()-style text message. - -|[ -printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc)); -]| - - - - - A fundamental type that describes a 32-bit flag bitfield, with 32-bit -mask indicating which of the bits in the field are explicitly set. - - Create a new sub-class of #GST_TYPE_FLAG_SET -which will pretty-print the human-readable flags -when serializing, for easier debugging. - - - - - - - a #GType of a #G_TYPE_FLAGS type. - - - - - - - The result of passing data to a pad. - -Note that the custom return values should not be exposed outside of the -element scope. - - Pre-defined custom success code. - - - Pre-defined custom success code (define your - custom success code to this to avoid compiler - warnings). - - - Elements can use values starting from - this (and higher) to define custom success - codes. - - - Data passing was ok. - - - Pad is not linked. - - - Pad is flushing. - - - Pad is EOS. - - - Pad is not negotiated. - - - Some (fatal) error occurred. Element generating - this error should post an error message using - GST_ELEMENT_ERROR() with more details. - - - This operation is not supported. - - - Elements can use values starting from - this (and lower) to define custom error codes. - - - Pre-defined custom error code (define your - custom error code to this to avoid compiler - warnings). - - - Pre-defined custom error code. - - - - Standard predefined formats - - undefined format - - - the default format of the pad/element. This can be - samples for raw audio, frames/fields for raw video (some, but not all, - elements support this; use @GST_FORMAT_TIME if you don't have a good - reason to query for samples/frames) - - - bytes - - - time in nanoseconds - - - buffers (few, if any, elements implement this as of - May 2009) - - - percentage of stream (few, if any, elements implement - this as of May 2009) - - - Return the format registered with the given nick. - - - The format with @nick or GST_FORMAT_UNDEFINED -if the format was not registered. - - - - - The nick of the format - - - - - - Get details about the given format. - - - The #GstFormatDefinition for @format or %NULL -on failure. - -MT safe. - - - - - The format to get details of - - - - - - Get a printable name for the given format. Do not modify or free. - - - a reference to the static name of the format -or %NULL if the format is unknown. - - - - - a #GstFormat - - - - - - Iterate all the registered formats. The format definition is read -only. - - - a GstIterator of #GstFormatDefinition. - - - - - Create a new GstFormat based on the nick or return an -already registered format with that nick. - - - A new GstFormat or an already registered format -with the same nick. - -MT safe. - - - - - The nick of the new format - - - - The description of the new format - - - - - - Get the unique quark for the given format. - - - the quark associated with the format or 0 if the format -is unknown. - - - - - a #GstFormat - - - - - - - A format definition - - - The unique id of this format - - - - A short nick of the format - - - - A longer description of the format - - - - A quark for the nick - - - - - A fundamental type that describes a fraction of an integer numerator -over an integer denominator - - - A fundamental type that describes a #GstFractionRange range - - - - - - - - - - - - - - - - - - - - - - - - A value which is guaranteed to never be returned by -gst_util_group_id_next(). - -Can be used as a default value in variables used to store group_id. - - - - - GhostPads are useful when organizing pipelines with #GstBin like elements. -The idea here is to create hierarchical element graphs. The bin element -contains a sub-graph. Now one would like to treat the bin-element like any -other #GstElement. This is where GhostPads come into play. A GhostPad acts as -a proxy for another pad. Thus the bin can have sink and source ghost-pads -that are associated with sink and source pads of the child elements. - -If the target pad is known at creation time, gst_ghost_pad_new() is the -function to use to get a ghost-pad. Otherwise one can use gst_ghost_pad_new_no_target() -to create the ghost-pad and use gst_ghost_pad_set_target() to establish the -association later on. - -Note that GhostPads add overhead to the data processing of a pipeline. - - - Create a new ghostpad with @target as the target. The direction will be taken -from the target pad. @target must be unlinked. - -Will ref the target. - - - a new #GstPad, or %NULL in -case of an error. - - - - - the name of the new pad, or %NULL to assign a default name - - - - the pad to ghost. - - - - - - Create a new ghostpad with @target as the target. The direction will be taken -from the target pad. The template used on the ghostpad will be @template. - -Will ref the target. - - - a new #GstPad, or %NULL in -case of an error. - - - - - the name of the new pad, or %NULL to assign a default name. - - - - the pad to ghost. - - - - the #GstPadTemplate to use on the ghostpad. - - - - - - Create a new ghostpad without a target with the given direction. -A target can be set on the ghostpad later with the -gst_ghost_pad_set_target() function. - -The created ghostpad will not have a padtemplate. - - - a new #GstPad, or %NULL in -case of an error. - - - - - the name of the new pad, or %NULL to assign a default name. - - - - the direction of the ghostpad - - - - - - Create a new ghostpad based on @templ, without setting a target. The -direction will be taken from the @templ. - - - a new #GstPad, or %NULL in -case of an error. - - - - - the name of the new pad, or %NULL to assign a default name - - - - the #GstPadTemplate to create the ghostpad from. - - - - - - Invoke the default activate mode function of a ghost pad. - - - %TRUE if the operation was successful. - - - - - the #GstPad to activate or deactivate. - - - - the parent of @pad or %NULL - - - - the requested activation mode - - - - whether the pad should be active or not. - - - - - - Invoke the default activate mode function of a proxy pad that is -owned by a ghost pad. - - - %TRUE if the operation was successful. - - - - - the #GstPad to activate or deactivate. - - - - the parent of @pad or %NULL - - - - the requested activation mode - - - - whether the pad should be active or not. - - - - - - Finish initialization of a newly allocated ghost pad. - -This function is most useful in language bindings and when subclassing -#GstGhostPad; plugin and application developers normally will not call this -function. Call this function directly after a call to g_object_new -(GST_TYPE_GHOST_PAD, "direction", @dir, ..., NULL). - This function is deprecated since 1.18 and does nothing -anymore. - - - %TRUE if the construction succeeds, %FALSE otherwise. - - - - - the newly allocated ghost pad - - - - - - Get the target pad of @gpad. Unref target pad after usage. - - - the target #GstPad, can be -%NULL if the ghostpad has no target set. Unref target pad after -usage. - - - - - the #GstGhostPad - - - - - - Set the new target of the ghostpad @gpad. Any existing target -is unlinked and links to the new target are established. if @newtarget is -%NULL the target will be cleared. - - - %TRUE if the new target could be set. This function - can return %FALSE when the internal pads could not be linked. - - - - - the #GstGhostPad - - - - the new pad target - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Macro to cast to a #GstIterator - - - - the #GstIterator value - - - - - Macro to get the cookie of a #GstIterator. The cookie of the -iterator is the value of the master cookie when the iterator -was created. -Whenever the iterator is iterated, the value is compared to the -value of the master cookie. If they are different, a concurrent -modification happened to the iterator and a resync is needed. - - - - the #GstIterator to get the cookie of - - - - - Macro to get the lock protecting the datastructure being iterated. - - - - the #GstIterator to get the lock of - - - - - Macro to get a pointer to where the master cookie is stored. The -master cookie protects the structure being iterated and gets updated -whenever the datastructure changes. - - - - the #GstIterator to get the master cookie of - - - - - A fundamental type that describes a #gint64 range - - - A fundamental type that describes a #gint range - - - A GstIterator is used to retrieve multiple objects from another object in -a threadsafe way. - -Various GStreamer objects provide access to their internal structures using -an iterator. - -Note that if calling a GstIterator function results in your code receiving -a refcounted object (with, say, g_value_get_object()), the refcount for that -object will not be increased. Your code is responsible for taking a reference -if it wants to continue using it later. - -The basic use pattern of an iterator is as follows: -|[<!-- language="C" --> - GstIterator *it = _get_iterator(object); - GValue item = G_VALUE_INIT; - done = FALSE; - while (!done) { - switch (gst_iterator_next (it, &amp;item)) { - case GST_ITERATOR_OK: - ...get/use/change item here... - g_value_reset (&amp;item); - break; - case GST_ITERATOR_RESYNC: - ...rollback changes to items... - gst_iterator_resync (it); - break; - case GST_ITERATOR_ERROR: - ...wrong parameters were given... - done = TRUE; - break; - case GST_ITERATOR_DONE: - done = TRUE; - break; - } - } - g_value_unset (&amp;item); - gst_iterator_free (it); -]| - - - The function to copy the iterator - - - - The function to get the next item in the iterator - - - - The function to be called for each item retrieved - - - - The function to call when a resync is needed. - - - - The function to call when the iterator is freed - - - - The iterator that is currently pushed with gst_iterator_push() - - - - The type of the object that this iterator will return - - - - The lock protecting the data structure and the cookie. - - - - The cookie; the value of the master_cookie when this iterator was - created. - - - - A pointer to the master cookie. - - - - the size of the iterator - - - - - - - - - Create a new iterator. This function is mainly used for objects -implementing the next/resync/free function to iterate a data structure. - -For each item retrieved, the @item function is called with the lock -held. The @free function is called when the iterator is freed. - - - the new #GstIterator. - -MT safe. - - - - - the size of the iterator structure - - - - #GType of children - - - - pointer to a #GMutex. - - - - pointer to a guint32 that is changed when the items in the - iterator changed. - - - - copy function - - - - function to get next item - - - - function to call on each item retrieved - - - - function to resync the iterator - - - - function to free the iterator - - - - - - Create a new iterator designed for iterating @list. - -The list you iterate is usually part of a data structure @owner and is -protected with @lock. - -The iterator will use @lock to retrieve the next item of the list and it -will then call the @item function before releasing @lock again. - -When a concurrent update to the list is performed, usually by @owner while -holding @lock, @master_cookie will be updated. The iterator implementation -will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to -the user of the iterator in the next call to gst_iterator_next(). - - - the new #GstIterator for @list. - -MT safe. - - - - - #GType of elements - - - - pointer to a #GMutex protecting the list. - - - - pointer to a guint32 that is incremented when the list - is changed. - - - - pointer to the list - - - - - - object owning the list - - - - function to call on each item retrieved - - - - - - This #GstIterator is a convenient iterator for the common -case where a #GstIterator needs to be returned but only -a single object has to be considered. This happens often -for the #GstPadIterIntLinkFunction. - - - the new #GstIterator for @object. - - - - - #GType of the passed object - - - - object that this iterator should return - - - - - - Copy the iterator and its state. - - - a new copy of @it. - - - - - a #GstIterator - - - - - - Create a new iterator from an existing iterator. The new iterator -will only return those elements that match the given compare function @func. -The first parameter that is passed to @func is the #GValue of the current -iterator element and the second parameter is @user_data. @func should -return 0 for elements that should be included in the filtered iterator. - -When this iterator is freed, @it will also be freed. - - - a new #GstIterator. - -MT safe. - - - - - The #GstIterator to filter - - - - the compare function to select elements - - - - user data passed to the compare function - - - - - - Find the first element in @it that matches the compare function @func. -@func should return 0 when the element is found. The first parameter -to @func will be the current element of the iterator and the -second parameter will be @user_data. -The result will be stored in @elem if a result is found. - -The iterator will not be freed. - -This function will return %FALSE if an error happened to the iterator -or if the element wasn't found. - - - Returns %TRUE if the element was found, else %FALSE. - -MT safe. - - - - - The #GstIterator to iterate - - - - the compare function to use - - - - pointer to a #GValue where to store the result - - - - user data passed to the compare function - - - - - - Folds @func over the elements of @iter. That is to say, @func will be called -as @func (object, @ret, @user_data) for each object in @it. The normal use -of this procedure is to accumulate the results of operating on the objects in -@ret. - -This procedure can be used (and is used internally) to implement the -gst_iterator_foreach() and gst_iterator_find_custom() operations. - -The fold will proceed as long as @func returns %TRUE. When the iterator has no -more arguments, %GST_ITERATOR_DONE will be returned. If @func returns %FALSE, -the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs -will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as -appropriate. - -The iterator will not be freed. - - - A #GstIteratorResult, as described above. - -MT safe. - - - - - The #GstIterator to fold over - - - - the fold function - - - - the seed value passed to the fold function - - - - user data passed to the fold function - - - - - - Iterate over all element of @it and call the given function @func for -each element. - - - the result call to gst_iterator_fold(). The iterator will not be -freed. - -MT safe. - - - - - The #GstIterator to iterate - - - - the function to call for each element. - - - - user data passed to the function - - - - - - Free the iterator. - -MT safe. - - - - - - - The #GstIterator to free - - - - - - Get the next item from the iterator in @elem. - -Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid -value. @elem must have been initialized to the type of the iterator or -initialized to zeroes with g_value_unset(). The caller is responsible for -unsetting or resetting @elem with g_value_unset() or g_value_reset() -after usage. - -When this function returns %GST_ITERATOR_DONE, no more elements can be -retrieved from @it. - -A return value of %GST_ITERATOR_RESYNC indicates that the element list was -concurrently updated. The user of @it should call gst_iterator_resync() to -get the newly updated list. - -A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error. - - - The result of the iteration. Unset @elem after usage. - -MT safe. - - - - - The #GstIterator to iterate - - - - pointer to hold next element - - - - - - Pushes @other iterator onto @it. All calls performed on @it are -forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is -popped again and calls are handled by @it again. - -This function is mainly used by objects implementing the iterator -next function to recurse into substructures. - -When gst_iterator_resync() is called on @it, @other will automatically be -popped. - -MT safe. - - - - - - - The #GstIterator to use - - - - The #GstIterator to push - - - - - - Resync the iterator. this function is mostly called -after gst_iterator_next() returned %GST_ITERATOR_RESYNC. - -When an iterator was pushed on @it, it will automatically be popped again -with this function. - -MT safe. - - - - - - - The #GstIterator to resync - - - - - - - This function will be called when creating a copy of @it and should -create a copy of all custom iterator fields or increase their -reference counts. - - - - - - - The original iterator - - - - The copied iterator - - - - - - A function to be passed to gst_iterator_fold(). - - - %TRUE if the fold should continue, %FALSE if it should stop. - - - - - the item to fold - - - - a #GValue collecting the result - - - - data passed to gst_iterator_fold() - - - - - - A function that is called by gst_iterator_foreach() for every element. - - - - - - - The item - - - - User data - - - - - - This function will be called when the iterator is freed. - -Implementors of a #GstIterator should implement this -function and pass it to the constructor of the custom iterator. -The function will be called with the iterator lock held. - - - - - - - the iterator - - - - - - The result of a #GstIteratorItemFunction. - - Skip this item - - - Return item - - - Stop after this item. - - - - The function that will be called after the next item of the iterator -has been retrieved. This function can be used to skip items or stop -the iterator. - -The function will be called with the iterator lock held. - - - the result of the operation. - - - - - the iterator - - - - the item being retrieved. - - - - - - The function that will be called when the next element of the iterator -should be retrieved. - -Implementors of a #GstIterator should implement this -function and pass it to the constructor of the custom iterator. -The function will be called with the iterator lock held. - - - the result of the operation. - - - - - the iterator - - - - a pointer to hold the next item - - - - - - The result of gst_iterator_next(). - - No more items in the iterator - - - An item was retrieved - - - Datastructure changed while iterating - - - An error happened - - - - This function will be called whenever a concurrent update happened -to the iterated datastructure. The implementor of the iterator should -restart the iterator from the beginning and clean up any state it might -have. - -Implementors of a #GstIterator should implement this -function and pass it to the constructor of the custom iterator. -The function will be called with the iterator lock held. - - - - - - - the iterator - - - - - - To be used in GST_PLUGIN_DEFINE if unsure about the licence. - - - - - GstLockFlags value alias for GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE - - - - - Library errors are for errors from the library being used by elements -(initializing, finalizing, settings, ...) - - a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - - - do not use this except as a placeholder for -deciding where to go while developing code. - - - used when the library could not be opened. - - - used when the library could not be closed. - - - used when the library doesn't accept settings. - - - used when the library generated an encoding error. - - - the number of library error types. - - - - - - - - - - Flags used when locking miniobjects - - lock for read access - - - lock for write access - - - lock for exclusive access - - - first flag that can be used for custom purposes - - - - Function prototype for a logging function that can be registered with -gst_debug_add_log_function(). -Use G_GNUC_NO_INSTRUMENT on that function. - - - - - - - a #GstDebugCategory - - - - a #GstDebugLevel - - - - file name - - - - function name - - - - line number - - - - a #GObject - - - - the message - - - - user data for the log function - - - - - - Transform four characters into a #guint32 fourcc value with host -endianness. - -|[ -guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G'); -]| - - - - the first character - - - the second character - - - the third character - - - the fourth character - - - - - GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE - - - - - Output a hexdump of @data. - -There is no need to finish the end of the message string with a newline -character, a newline character will be added automatically. - - - - message string to log with the data - - - pointer to the data to output - - - length of the data to output - - - - - Output a logging message belonging to the given object in the default category. - -There is no need to finish the end of the message string with a newline -character, a newline character will be added automatically. - - - - the #GObject the message belongs to - - - message string to log with the data - - - pointer to the data to output - - - length of the data to output - - - - - - - - - - - - A flags word containing #GstMemoryFlags flags set on @mem - - - - a #GstMemory. - - - - - Gives the status of a specific flag on a @mem. - - - - a #GstMemory. - - - the #GstMemoryFlags to check. - - - - - Clear a specific flag on a @mem. - - - - a #GstMemory. - - - the #GstMemoryFlags to clear. - - - - - Check if @mem can't be mapped via gst_memory_map() without any preconditions - - - - a #GstMemory. - - - - - Check if @mem cannot be shared between buffers - - - - a #GstMemory. - - - - - Check if @mem is physically contiguous. - - - - a #GstMemory. - - - - - Check if @mem is readonly. - - - - a #GstMemory. - - - - - Check if the padding in @mem is 0 filled. - - - - a #GstMemory. - - - - - Check if the prefix in @mem is 0 filled. - - - - a #GstMemory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the sequence number of @message. - - - - a #GstMessage - - - - - - - - - - - - Get the object that posted @message. - - - - a #GstMessage - - - - - Get the name of the object that posted @message. Returns "(NULL)" if -the message has no source object set. - - - - a #GstMessage - - - - - Get the timestamp of @message. This is the timestamp when the message -was created. - - - - a #GstMessage - - - - - Get the #GstMessageType of @message. - - - - a #GstMessage - - - - - Check if the message is in the extended message group - - - - a #GstMessage - - - - - Get a constant string representation of the #GstMessageType of @message. - - - - a #GstMessage - - - - - - - - - - - - - - - - - - - - - - - - - - A flags word containing #GstMetaFlags flags set on @meta - - - - a #GstMeta. - - - - - Gives the status of a specific flag on a metadata. - - - - a #GstMeta. - - - the #GstMetaFlags to check. - - - - - Sets a metadata flag on a metadata. - - - - a #GstMeta. - - - the #GstMetaFlags to set. - - - - - Clears a metadata flag. - - - - a #GstMeta. - - - the #GstMetaFlags to clear. - - - - - This metadata stays relevant as long as memory layout is unchanged. - - - - - Check if the transform type is a copy transform - - - - a transform type - - - - - - - - - - - - - - - - - - - - - - - - - - This macro returns the entire set of flags for the mini-object. - - - - MiniObject to return flags for. - - - - - This macro checks to see if the given flag is set. - - - - MiniObject to check for flags. - - - Flag to check for - - - - - This macro sets the given bits. - - - - MiniObject to set flag in. - - - Flag to set, can by any number of bits in guint32. - - - - - This macro unsets the given bits. - - - - MiniObject to unset flag in. - - - Flag to set, must be a single bit in guint32. - - - - - Check if @obj is lockable. A lockable object can be locked and unlocked with -gst_mini_object_lock() and gst_mini_object_unlock(). - - - - a #GstMiniObject - - - - - Get access to the reference count field of the mini-object. - - - - a #GstMiniObject - - - - - Get the reference count value of the mini-object. - - - - a #GstMiniObject - - - - - This macro returns the type of the mini-object. - - - - MiniObject to return type for. - - - - - Constant that defines one GStreamer millisecond. - - - - - Flags used when mapping memory - - map for read access - - - map for write access - - - first flag that can be used for custom purposes - - - - A structure containing the result of a map operation such as -gst_memory_map(). It contains the data and size. - - - a pointer to the mapped memory - - - - flags used when mapping the memory - - - - a pointer to the mapped data - - - - - - the valid size in @data - - - - the maximum bytes in @data - - - - extra private user_data that the implementation of the memory - can use to store extra info. - - - - - - - - - - - - GstMemory is a lightweight refcounted object that wraps a region of memory. -They are typically used to manage the data of a #GstBuffer. - -A GstMemory object has an allocated region of memory of maxsize. The maximum -size does not change during the lifetime of the memory object. The memory -also has an offset and size property that specifies the valid range of memory -in the allocated region. - -Memory is usually created by allocators with a gst_allocator_alloc() -method call. When %NULL is used as the allocator, the default allocator will -be used. - -New allocators can be registered with gst_allocator_register(). -Allocators are identified by name and can be retrieved with -gst_allocator_find(). gst_allocator_set_default() can be used to change the -default allocator. - -New memory can be created with gst_memory_new_wrapped() that wraps the memory -allocated elsewhere. - -Refcounting of the memory block is performed with gst_memory_ref() and -gst_memory_unref(). - -The size of the memory can be retrieved and changed with -gst_memory_get_sizes() and gst_memory_resize() respectively. - -Getting access to the data of the memory is performed with gst_memory_map(). -The call will return a pointer to offset bytes into the region of memory. -After the memory access is completed, gst_memory_unmap() should be called. - -Memory can be copied with gst_memory_copy(), which will return a writable -copy. gst_memory_share() will create a new memory block that shares the -memory with an existing memory block at a custom offset and with a custom -size. - -Memory can be efficiently merged when gst_memory_is_span() returns %TRUE. - - - parent structure - - - - pointer to the #GstAllocator - - - - parent memory block - - - - the maximum size allocated - - - - the alignment of the memory - - - - the offset where valid data starts - - - - the size of valid data - - - - Allocate a new memory block that wraps the given @data. - -The prefix/padding must be filled with 0 if @flags contains -#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. - - - a new #GstMemory. - - - - - #GstMemoryFlags - - - - data to - wrap - - - - - - allocated size of @data - - - - offset in @data - - - - size of valid data - - - - user_data - - - - called with @user_data when the memory is freed - - - - - - Return a copy of @size bytes from @mem starting from @offset. This copy is -guaranteed to be writable. @size can be set to -1 to return a copy -from @offset to the end of the memory region. - - - a new #GstMemory. - - - - - a #GstMemory - - - - offset to copy from - - - - size to copy, or -1 to copy to the end of the memory region - - - - - - Get the current @size, @offset and @maxsize of @mem. - - - the current size of @mem - - - - - a #GstMemory - - - - pointer to offset - - - - pointer to maxsize - - - - - - Initializes a newly allocated @mem with the given parameters. This function -will call gst_mini_object_init() with the default memory parameters. - - - - - - - a #GstMemory - - - - #GstMemoryFlags - - - - the #GstAllocator - - - - the parent of @mem - - - - the total size of the memory - - - - the alignment of the memory - - - - The offset in the memory - - - - the size of valid data in the memory - - - - - - Check if @mem1 and mem2 share the memory with a common parent memory object -and that the memory is contiguous. - -If this is the case, the memory of @mem1 and @mem2 can be merged -efficiently by performing gst_memory_share() on the parent object from -the returned @offset. - - - %TRUE if the memory is contiguous and of a common parent. - - - - - a #GstMemory - - - - a #GstMemory - - - - a pointer to a result offset - - - - - - Check if @mem if allocated with an allocator for @mem_type. - - - %TRUE if @mem was allocated from an allocator for @mem_type. - - - - - a #GstMemory - - - - a memory type - - - - - - Create a #GstMemory object that is mapped with @flags. If @mem is mappable -with @flags, this function returns the mapped @mem directly. Otherwise a -mapped copy of @mem is returned. - -This function takes ownership of old @mem and returns a reference to a new -#GstMemory. - - - a #GstMemory object mapped -with @flags or %NULL when a mapping is not possible. - - - - - a #GstMemory - - - - pointer for info - - - - mapping flags - - - - - - Fill @info with the pointer and sizes of the memory in @mem that can be -accessed according to @flags. - -This function can return %FALSE for various reasons: -- the memory backed by @mem is not accessible with the given @flags. -- the memory was already mapped with a different mapping. - -@info and its contents remain valid for as long as @mem is valid and -until gst_memory_unmap() is called. - -For each gst_memory_map() call, a corresponding gst_memory_unmap() call -should be done. - - - %TRUE if the map operation was successful. - - - - - a #GstMemory - - - - pointer for info - - - - mapping flags - - - - - - Increase the refcount of this memory. - - - @memory (for convenience when doing assignments) - - - - - The memory to refcount - - - - - - Resize the memory region. @mem should be writable and offset + size should be -less than the maxsize of @mem. - -#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be -cleared when offset or padding is increased respectively. - - - - - - - a #GstMemory - - - - a new offset - - - - a new size - - - - - - Return a shared copy of @size bytes from @mem starting from @offset. No -memory copy is performed and the memory region is simply shared. The result -is guaranteed to be non-writable. @size can be set to -1 to return a shared -copy from @offset to the end of the memory region. - - - a new #GstMemory. - - - - - a #GstMemory - - - - offset to share from - - - - size to share, or -1 to share to the end of the memory region - - - - - - Release the memory obtained with gst_memory_map() - - - - - - - a #GstMemory - - - - a #GstMapInfo - - - - - - Decrease the refcount of a memory, freeing it if the refcount reaches 0. - - - - - - - the memory to refcount - - - - - - - Copy @size bytes from @mem starting at @offset and return them wrapped in a -new GstMemory object. -If @size is set to -1, all bytes starting at @offset are copied. - - - a new #GstMemory object wrapping a copy of the requested region in -@mem. - - - - - a #GstMemory - - - - an offset - - - - a size or -1 - - - - - - Flags for wrapped memory. - - memory is readonly. It is not allowed to map the -memory with #GST_MAP_WRITE. - - - memory must not be shared. Copies will have to be -made when this memory needs to be shared between buffers. - - - the memory prefix is filled with 0 bytes - - - the memory padding is filled with 0 bytes - - - the memory is physically contiguous. (Since: 1.2) - - - the memory can't be mapped via gst_memory_map() without any preconditions. (Since: 1.2) - - - first flag that can be used for custom purposes - - - - Check if @mem1 and @mem2 occupy contiguous memory and return the offset of -@mem1 in the parent buffer in @offset. - - - %TRUE if @mem1 and @mem2 are in contiguous memory. - - - - - a #GstMemory - - - - a #GstMemory - - - - a result offset - - - - - - Get the memory of @mem that can be accessed according to the mode specified -in @info's flags. The function should return a pointer that contains at least -@maxsize bytes. - - - a pointer to memory of which at least @maxsize bytes can be -accessed according to the access pattern in @info's flags. - - - - - a #GstMemory - - - - the #GstMapInfo to map with - - - - size to map - - - - - - Get the memory of @mem that can be accessed according to the mode specified -in @flags. The function should return a pointer that contains at least -@maxsize bytes. - - - a pointer to memory of which at least @maxsize bytes can be -accessed according to the access pattern in @flags. - - - - - a #GstMemory - - - - size to map - - - - access mode for the memory - - - - - - Share @size bytes from @mem starting at @offset and return them wrapped in a -new GstMemory object. If @size is set to -1, all bytes starting at @offset are -shared. This function does not make a copy of the bytes in @mem. - - - a new #GstMemory object sharing the requested region in @mem. - - - - - a #GstMemory - - - - an offset - - - - a size or -1 - - - - - - Release the pointer previously retrieved with gst_memory_map() with @info. - - - - - - - a #GstMemory - - - - a #GstMapInfo - - - - - - Release the pointer previously retrieved with gst_memory_map(). - - - - - - - a #GstMemory - - - - - - Messages are implemented as a subclass of #GstMiniObject with a generic -#GstStructure 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 #GstBus. - -The basic use pattern of posting a message on a #GstBus is as follows: -|[<!-- language="C" --> - gst_bus_post (bus, gst_message_new_eos()); -]| - -A #GstElement usually posts messages on the bus provided by the parent -container using gst_element_post_message(). - - - the parent structure - - - - the #GstMessageType of the message - - - - the timestamp of the message - - - - the src of the message - - - - the sequence number of the message - - - - - - - - - - Create a new application-typed message. GStreamer will never create these -messages; they are a gift from us to you. Enjoy. - - - The new application message. - -MT safe. - - - - - The object originating the message. - - - - the structure for the message. The message - will take ownership of the structure. - - - - - - The message is posted when elements completed an ASYNC state change. -@running_time contains the time of the desired running_time when this -elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time -means that the element has no clock interaction and thus doesn't care about -the running_time of the pipeline. - - - The new async_done message. - -MT safe. - - - - - The object originating the message. - - - - the desired running_time - - - - - - This message is posted by elements when they start an ASYNC state change. - - - The new async_start message. - -MT safe. - - - - - The object originating the 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. - - - The new buffering message. - - - - - The object originating the message. - - - - The buffering percent - - - - - - 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. - - - The new clock lost message. - -MT safe. - - - - - The object originating the message. - - - - the clock that was lost - - - - - - 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. - - - the new provide clock message. - -MT safe. - - - - - The object originating the message. - - - - the clock it provides - - - - %TRUE if the sender can provide a clock - - - - - - 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 %NULL. - - - The new message. - -MT safe. - - - - - The #GstMessageType to distinguish messages - - - - The object originating the message. - - - - the structure for the - message. The message will take ownership of the structure. - - - - - - Creates a new device-added message. The device-added message is produced by -#GstDeviceProvider or a #GstDeviceMonitor. They announce the appearance -of monitored devices. - - - a newly allocated #GstMessage - - - - - The #GstObject that created the message - - - - The new #GstDevice - - - - - - Creates a new device-changed message. The device-changed message is produced -by #GstDeviceProvider or a #GstDeviceMonitor. They announce that a device -properties has changed and @device represent the new modified version of @changed_device. - - - a newly allocated #GstMessage - - - - - The #GstObject that created the message - - - - The newly created device representing @replaced_device - with its new configuration. - - - - - - - - - Creates a new device-removed message. The device-removed message is produced -by #GstDeviceProvider or a #GstDeviceMonitor. They announce the -disappearance of monitored devices. - - - a newly allocated #GstMessage - - - - - The #GstObject that created the message - - - - The removed #GstDevice - - - - - - 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. - - - The new duration-changed message. - -MT safe. - - - - - The object originating the message. - - - - - - 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 %NULL. - - - The new element message. - -MT safe. - - - - - The object originating the message. - - - - The structure for the - message. The message will take ownership of the structure. - - - - - - 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. - - - The new eos message. - -MT safe. - - - - - The object originating the 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. - - - the new error message. - -MT safe. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - - - 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. - - - the new error message. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - A GstStructure with details - - - - - - This message is posted when an element has a new local #GstContext. - - - The new have-context message. - -MT safe. - - - - - The object originating the message. - - - - the context - - - - - - Create a new info message. The message will make copies of @error and -@debug. - - - the new info message. - -MT safe. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - - - Create a new info message. The message will make copies of @error and -@debug. - - - the new warning message. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - A GstStructure with details - - - - - - Creates a new instant-rate-request message. Elements handling the -instant-rate-change event must post this message. The message is -handled at the pipeline, and allows the pipeline to select the -running time when the rate change should happen and to send an -@GST_EVENT_INSTANT_RATE_SYNC_TIME event to notify the elements -in the pipeline. - - - a newly allocated #GstMessage - - - - - The #GstObject that posted the message - - - - the rate multiplier factor that should be applied - - - - - - This message can be posted by elements when their latency requirements have -changed. - - - The new latency message. - -MT safe. - - - - - The object originating the message. - - - - - - This message is posted when an element needs a specific #GstContext. - - - The new need-context message. - -MT safe. - - - - - The object originating the message. - - - - The context type that is needed - - - - - - Create a new clock message. This message is posted whenever the -pipeline selects a new clock for the pipeline. - - - The new new clock message. - -MT safe. - - - - - The object originating the message. - - - - the new selected clock - - - - - - 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. - - - The new qos message. - - - - - The object originating the message. - - - - a #GstProgressType - - - - a progress code - - - - free, user visible text describing the progress - - - - - - - - a newly allocated #GstMessage - - - - - The #GstObject whose property changed (may or may not be a #GstElement) - - - - name of the property that changed - - - - new property value, or %NULL - - - - - - 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). - -@running_time, @stream_time, @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. - - - The new qos message. - -MT safe. - - - - - The object originating the message. - - - - if the message was generated by a live element - - - - the running time of the buffer that generated the message - - - - the stream time of the buffer that generated the message - - - - the timestamps of the buffer that generated the message - - - - the duration of the buffer that generated the 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 gst_message_add_redirect_entry() 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. - - - a newly allocated #GstMessage - - - - - The #GstObject whose property changed (may or may not be a #GstElement) - - - - location string for the new entry - - - - tag list for the new entry - - - - structure for the new entry - - - - - - 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. - - - the new request state message. - -MT safe. - - - - - The object originating the message. - - - - The new requested state - - - - - - This message is posted when the pipeline running-time should be reset to -@running_time, like after a flushing seek. - - - The new reset_time message. - -MT safe. - - - - - The object originating the message. - - - - the requested running-time - - - - - - 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. - - - the new segment done message. - -MT safe. - - - - - The object originating the message. - - - - The format of the position being done - - - - The position of the segment being done - - - - - - 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. - - - the new segment start message. - -MT safe. - - - - - The object originating the message. - - - - The format of the position being played - - - - The position of the segment being played - - - - - - Create a state change message. This message is posted whenever an element -changed its state. - - - the new state change message. - -MT safe. - - - - - The object originating the message. - - - - the previous state - - - - the new (current) state - - - - the pending (target) state - - - - - - 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. - - - the new state dirty message. - -MT safe. - - - - - The object originating the message - - - - - - 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. - - - the new step_done message. - -MT safe. - - - - - The object originating the message. - - - - the format of @amount - - - - the amount of stepped data - - - - the rate of the stepped amount - - - - is this an flushing step - - - - is this an intermediate step - - - - the duration of the data - - - - the step caused EOS - - - - - - 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. - - - The new step_start message. - -MT safe. - - - - - The object originating the message. - - - - if the step is active or queued - - - - the format of @amount - - - - the amount of stepped data - - - - the rate of the stepped amount - - - - is this an flushing step - - - - is this an intermediate step - - - - - - Creates a new stream-collection message. The message is used to announce new -#GstStreamCollection - - - a newly allocated #GstMessage - - - - - The #GstObject that created the message - - - - The #GstStreamCollection - - - - - - 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. - - - The new stream_start message. - -MT safe. - - - - - The object originating the message. - - - - - - Create a new stream status message. This message is posted when a streaming -thread is created/destroyed or when the state changed. - - - the new stream status message. - -MT safe. - - - - - The object originating the message. - - - - The stream status type. - - - - the owner element of @src. - - - - - - 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 #GstStreamCollection to which the various streams -belong to. - -Users of gst_message_new_streams_selected() can add the selected streams with -gst_message_streams_selected_add(). - - - a newly allocated #GstMessage - - - - - The #GstObject that created the message - - - - The #GstStreamCollection - - - - - - 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. - - - the new structure change message. - -MT safe. - - - - - The object originating the message. - - - - The change type. - - - - The owner element of @src. - - - - Whether the structure change is busy. - - - - - - 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. - - - the new tag message. - -MT safe. - - - - - The object originating the message. - - - - the tag list for the message. - - - - - - Create a new TOC message. The message is posted by elements -that discovered or updated a TOC. - - - a new TOC message. - -MT safe. - - - - - the object originating the message. - - - - #GstToc structure for the message. - - - - whether TOC was updated or not. - - - - - - Create a new warning message. The message will make copies of @error and -@debug. - - - the new warning message. - -MT safe. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - - - Create a new warning message. The message will make copies of @error and -@debug. - - - the new warning message. - - - - - The object originating the message. - - - - The GError for this message. - - - - A debugging string. - - - - A GstStructure with details - - - - - - 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. - - - - - - - a #GstMessage of type %GST_MESSAGE_REDIRECT - - - - location string for the new entry - - - - tag list for the new entry - - - - structure for the new entry - - - - - - Creates a copy of the message. Returns a copy of the message. - - - a new copy of @msg. - -MT safe - - - - - the message to copy - - - - - - - - the number of entries stored in the message - - - - - a #GstMessage of type %GST_MESSAGE_REDIRECT - - - - - - Retrieve the sequence number of a message. - -Messages have ever-incrementing sequence numbers, which may also be set -explicitly via gst_message_set_seqnum(). 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. - - - The message's sequence number. - -MT safe. - - - - - A #GstMessage. - - - - - - Extracts the object managing the streaming thread from @message. - - - 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. - - - - - A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. - - - - - - Access the structure of the message. - - - 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. - - - - - The #GstMessage. - - - - - - Checks if @message has the given @name. This function is usually used to -check the name of a custom message. - - - %TRUE if @name matches the name of the message structure. - - - - - The #GstMessage. - - - - name to check - - - - - - Extract the running_time from the async_done message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE. - - - - Result location for the running_time or %NULL - - - - - - Extracts the buffering percent from the GstMessage. see also -gst_message_new_buffering(). - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_BUFFERING. - - - - Return location for the percent. - - - - - - Extracts the buffering stats values from @message. - - - - - - - A valid #GstMessage of type GST_MESSAGE_BUFFERING. - - - - a buffering mode, or %NULL - - - - the average input rate, or %NULL - - - - the average output rate, or %NULL - - - - amount of buffering time left in - milliseconds, or %NULL - - - - - - Extracts the lost clock from the GstMessage. -The clock object returned remains valid until the message is freed. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. - - - - a pointer to hold the lost clock - - - - - - Extracts the clock and ready flag from the GstMessage. -The clock object returned remains valid until the message is freed. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. - - - - a pointer to hold a clock - object, or %NULL - - - - a pointer to hold the ready flag, or %NULL - - - - - - Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. - - - a #gboolean indicating if the parsing succeeded. - - - - - a GST_MESSAGE_NEED_CONTEXT type message - - - - the context type, or %NULL - - - - - - Parses a device-added message. The device-added message is produced by -#GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance -of monitored devices. - - - - - - - a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED - - - - A location where to store a - pointer to the new #GstDevice, or %NULL - - - - - - Parses a device-changed message. The device-changed message is produced by -#GstDeviceProvider or a #GstDeviceMonitor. It announces the -disappearance of monitored devices. * It announce that a device properties has -changed and @device represents the new modified version of @changed_device. - - - - - - - a #GstMessage of type %GST_MESSAGE_DEVICE_CHANGED - - - - A location where to store a - pointer to the updated version of the #GstDevice, or %NULL - - - - A location where to store a - pointer to the old version of the #GstDevice, or %NULL - - - - - - Parses a device-removed message. The device-removed message is produced by -#GstDeviceProvider or a #GstDeviceMonitor. It announces the -disappearance of monitored devices. - - - - - - - a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED - - - - A location where to store a - pointer to the removed #GstDevice, or %NULL - - - - - - 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: -|[<!-- language="C" --> - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_ERROR: { - GError *err = NULL; - gchar *dbg_info = NULL; - - gst_message_parse_error (msg, &amp;err, &amp;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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_ERROR. - - - - location for the GError - - - - location for the debug message, - or %NULL - - - - - - Returns the optional details structure, may be NULL if none. -The returned structure must not be freed. - - - - - - - The message object - - - - A pointer to the returned details - - - - - - Extract the group from the STREAM_START message. - - - %TRUE if the message had a group id set, %FALSE otherwise - -MT safe. - - - - - A valid #GstMessage of type GST_MESSAGE_STREAM_START. - - - - Result location for the group id or - %NULL - - - - - - Extract the context from the HAVE_CONTEXT message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT. - - - - Result location for the - context or %NULL - - - - - - 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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_INFO. - - - - location for the GError - - - - location for the debug message, - or %NULL - - - - - - Returns the optional details structure, may be NULL if none -The returned structure must not be freed. - - - - - - - The message object - - - - A pointer to the returned details structure - - - - - - Parses the rate_multiplier from the instant-rate-request message. - - - - - - - a #GstMessage of type %GST_MESSAGE_INSTANT_RATE_REQUEST - - - - return location for the rate, or %NULL - - - - - - Extracts the new clock from the GstMessage. -The clock object returned remains valid until the message is freed. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. - - - - a pointer to hold the selected - new clock - - - - - - Parses the progress @type, @code and @text. - - - - - - - A valid #GstMessage of type GST_MESSAGE_PROGRESS. - - - - location for the type - - - - location for the code - - - - location for the text - - - - - - Parses a property-notify message. These will be posted on the bus only -when set up with gst_element_add_property_notify_watch() or -gst_element_add_property_deep_notify_watch(). - - - - - - - a #GstMessage of type %GST_MESSAGE_PROPERTY_NOTIFY - - - - location where to store a - pointer to the object whose property got changed, or %NULL - - - - return location for - the name of the property that got changed, or %NULL - - - - return location for - the new value of the property that got changed, or %NULL. This will - only be set if the property notify watch was told to include the value - when it was set up - - - - - - 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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_QOS. - - - - if the message was generated by a live element - - - - the running time of the buffer that - generated the message - - - - the stream time of the buffer that - generated the message - - - - the timestamps of the buffer that - generated the message - - - - the duration of the buffer that - generated the message - - - - - - Extract the QoS stats representing the history of the current continuous -pipeline playback period. - -When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are -invalid. Values of -1 for either @processed or @dropped mean unknown values. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_QOS. - - - - 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). - - - - Total number of units correctly processed - since the last state change to READY or a flushing operation. - - - - Total number of units dropped since the last - state change to READY or a flushing operation. - - - - - - Extract the QoS values that have been calculated/analysed from the QoS data - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_QOS. - - - - The difference of the running-time against - the deadline. - - - - Long term prediction of the ideal rate - relative to normal rate to get optimal quality. - - - - An element dependent integer value that - specifies the current quality level of the element. The default - maximum quality is 1000000. - - - - - - Parses the location and/or structure from the entry with the given index. -The index must be between 0 and gst_message_get_num_redirect_entries() - 1. -Returned pointers are valid for as long as this message exists. - - - - - - - a #GstMessage of type %GST_MESSAGE_REDIRECT - - - - index of the entry to parse - - - - return location for - the pointer to the entry's location string, or %NULL - - - - return location for - the pointer to the entry's tag list, or %NULL - - - - return location - for the pointer to the entry's structure, or %NULL - - - - - - Extract the requested state from the request_state message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE. - - - - Result location for the requested state or %NULL - - - - - - Extract the running-time from the RESET_TIME message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_RESET_TIME. - - - - Result location for the running_time or - %NULL - - - - - - Extracts the position and format from the segment done message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE. - - - - Result location for the format, or %NULL - - - - Result location for the position, or %NULL - - - - - - Extracts the position and format from the segment start message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_SEGMENT_START. - - - - Result location for the format, or %NULL - - - - Result location for the position, or %NULL - - - - - - Extracts the old and new states from the GstMessage. - -Typical usage of this function might be: -|[<!-- language="C" --> - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_STATE_CHANGED: { - GstState old_state, new_state; - - gst_message_parse_state_changed (msg, &amp;old_state, &amp;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. - - - - - - - a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED - - - - the previous state, or %NULL - - - - the new (current) state, or %NULL - - - - the pending (target) state, or %NULL - - - - - - Extract the values the step_done message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_STEP_DONE. - - - - result location for the format - - - - result location for the amount - - - - result location for the rate - - - - result location for the flush flag - - - - result location for the intermediate flag - - - - result location for the duration - - - - result location for the EOS flag - - - - - - Extract the values from step_start message. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_STEP_DONE. - - - - result location for the active flag - - - - result location for the format - - - - result location for the amount - - - - result location for the rate - - - - result location for the flush flag - - - - result location for the intermediate flag - - - - - - Parses a stream-collection message. - - - - - - - a #GstMessage of type %GST_MESSAGE_STREAM_COLLECTION - - - - A location where to store a - pointer to the #GstStreamCollection, or %NULL - - - - - - 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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. - - - - A pointer to hold the status type - - - - The owner element of the message source - - - - - - Parses a streams-selected message. - - - - - - - a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED - - - - A location where to store a - pointer to the #GstStreamCollection, or %NULL - - - - - - Extracts the change type and completion status from the GstMessage. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. - - - - A pointer to hold the change type - - - - The owner element of the - message source - - - - a pointer to hold whether the change is in - progress or has been completed - - - - - - 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: -|[<!-- language="C" --> - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_TAG: { - GstTagList *tags = NULL; - - gst_message_parse_tag (msg, &amp;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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_TAG. - - - - return location for the tag-list. - - - - - - Extract the TOC from the #GstMessage. The TOC returned in the -output argument is a copy; the caller must free it with -gst_toc_unref() when done. - -MT safe. - - - - - - - a valid #GstMessage of type GST_MESSAGE_TOC. - - - - return location for the TOC. - - - - return location for the updated flag. - - - - - - 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. - - - - - - - A valid #GstMessage of type GST_MESSAGE_WARNING. - - - - location for the GError - - - - location for the debug message, - or %NULL - - - - - - Returns the optional details structure, may be NULL if none -The returned structure must not be freed. - - - - - - - The message object - - - - A pointer to the returned details structure - - - - - - Convenience macro to increase the reference count of the message. - - - @msg (for convenience when doing assignments) - - - - - the message to ref - - - - - - Configures the buffering stats values in @message. - - - - - - - A valid #GstMessage of type GST_MESSAGE_BUFFERING. - - - - a buffering mode - - - - the average input rate - - - - the average output rate - - - - amount of buffering time left in milliseconds - - - - - - 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. - - - - - - - the message - - - - the group id - - - - - - Set the QoS stats representing the history of the current continuous pipeline -playback period. - -When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are -invalid. Values of -1 for either @processed or @dropped mean unknown values. - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_QOS. - - - - 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). - - - - Total number of units correctly processed since the last state -change to READY or a flushing operation. - - - - Total number of units dropped since the last state change to READY -or a flushing operation. - - - - - - Set the QoS values that have been calculated/analysed from the QoS data - -MT safe. - - - - - - - A valid #GstMessage of type GST_MESSAGE_QOS. - - - - The difference of the running-time against the deadline. - - - - Long term prediction of the ideal rate relative to normal rate -to get optimal quality. - - - - An element dependent integer value that specifies the current -quality level of the element. The default maximum quality is 1000000. - - - - - - 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 gst_message_get_seqnum() -for more information. - -MT safe. - - - - - - - A #GstMessage. - - - - A sequence number. - - - - - - Configures the object handling the streaming thread. This is usually a -GstTask object but other objects might be added in the future. - - - - - - - A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. - - - - the object controlling the streaming - - - - - - Adds the @stream to the @message. - - - - - - - a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED - - - - a #GstStream to add to @message - - - - - - Returns the number of streams contained in the @message. - - - The number of streams contained within. - - - - - a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED - - - - - - Retrieves the #GstStream with index @index from the @message. - - - A #GstStream - - - - - a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED - - - - Index of the stream to retrieve - - - - - - Convenience macro to decrease the reference count of the message, possibly -freeing it. - - - - - - - the message to unref - - - - - - Get a writable version of the structure. - - - 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 -%NULL. - -MT safe. - - - - - The #GstMessage. - - - - - - Modifies a pointer to a #GstMessage to point to a different #GstMessage. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -message is unreffed, the new one is reffed). - -Either @new_message or the #GstMessage pointed to by @old_message may be %NULL. - - - %TRUE if @new_message was different from @old_message - - - - - pointer to a - pointer to a #GstMessage to be replaced. - - - - pointer to a #GstMessage that will - replace the message pointed to by @old_message. - - - - - - - The different message types that are available. - - an undefined message - - - end-of-stream reached in a pipeline. The application will -only receive this message in the PLAYING state and every time it sets a -pipeline to PLAYING that is in the EOS state. The application can perform a -flushing seek in the pipeline, which will undo the EOS state again. - - - an error occurred. When the application receives an error -message it should stop playback of the pipeline and not assume that more -data will be played. It is possible to specify a redirection url to the error -messages by setting a `redirect-location` field into the error message, application -or high level bins might use the information as required. - - - a warning occurred. - - - an info message occurred - - - a tag was found. - - - the pipeline is buffering. When the application -receives a buffering message in the PLAYING state for a non-live pipeline it -must PAUSE the pipeline until the buffering completes, when the percentage -field in the message is 100%. For live pipelines, no action must be -performed and the buffering percentage can be used to inform the user about -the progress. - - - a state change happened - - - an element changed state in a streaming thread. -This message is deprecated. - - - a stepping operation finished. - - - an element notifies its capability of providing - a clock. This message is used internally and - never forwarded to the application. - - - The current clock as selected by the pipeline became - unusable. The pipeline will select a new clock on - the next PLAYING state change. The application - should set the pipeline to PAUSED and back to - PLAYING when this message is received. - - - a new clock was selected in the pipeline. - - - the structure of the pipeline changed. This -message is used internally and never forwarded to the application. - - - status about a stream, emitted when it starts, - stops, errors, etc.. - - - message posted by the application, possibly - via an application-specific element. - - - element-specific message, see the specific element's - documentation - - - pipeline started playback of a segment. This -message is used internally and never forwarded to the application. - - - pipeline completed playback of a segment. This -message is forwarded to the application after all elements that posted -@GST_MESSAGE_SEGMENT_START posted a GST_MESSAGE_SEGMENT_DONE message. - - - The duration of a pipeline changed. The -application can get the new duration with a duration query. - - - Posted by elements when their latency changes. The -application should recalculate and distribute a new latency. - - - Posted by elements when they start an ASYNC -#GstStateChange. This message is not forwarded to the application but is used -internally. - - - Posted by elements when they complete an ASYNC -#GstStateChange. The application will only receive this message from the toplevel -pipeline. - - - Posted by elements when they want the pipeline to -change state. This message is a suggestion to the application which can -decide to perform the state change on (part of) the pipeline. - - - A stepping operation was started. - - - A buffer was dropped or an element changed its processing -strategy for Quality of Service reasons. - - - A progress message. - - - A new table of contents (TOC) was found or previously found TOC -was updated. - - - Message to request resetting the pipeline's - running time from the pipeline. This is an internal message which - applications will likely never receive. - - - Message indicating start of a new stream. Useful - e.g. when using playbin in gapless playback mode, to get notified when - the next title actually starts playing (which will be some time after - the URI for the next title has been set). - - - Message indicating that an element wants a specific context (Since: 1.2) - - - Message indicating that an element created a context (Since: 1.2) - - - Message is an extended message type (see below). - These extended message IDs can't be used directly with mask-based API - like gst_bus_poll() or gst_bus_timed_pop_filtered(), but you can still - filter for GST_MESSAGE_EXTENDED and then check the result for the - specific type. (Since: 1.4) - - - Message indicating a #GstDevice was added to - a #GstDeviceProvider (Since: 1.4) - - - Message indicating a #GstDevice was removed - from a #GstDeviceProvider (Since: 1.4) - - - Message indicating a #GObject property has - changed (Since: 1.10) - - - Message indicating a new #GstStreamCollection - is available (Since: 1.10) - - - Message indicating the active selection of - #GstStreams has changed (Since: 1.10) - - - Message indicating to request the application to - try to play the given URL(s). Useful if for example a HTTP 302/303 - response is received with a non-HTTP URL inside. (Since: 1.10) - - - Message indicating a #GstDevice was changed - a #GstDeviceProvider (Since: 1.16) - - - Message sent by elements to request the - running time from the pipeline when an instant rate change should - be applied (which may be in the past when the answer arrives). (Since: 1.18) - - - mask for all of the above messages. - - - Get a printable name for the given message type. Do not modify or free. - - - a reference to the static name of the message. - - - - - the message type - - - - - - Get the unique quark for the given message type. - - - the quark associated with the message type - - - - - the message type - - - - - - - The #GstMeta structure should be included as the first member of a #GstBuffer -metadata structure. The structure defines the API of the metadata and should -be accessible to all elements using the metadata. - -A metadata API is registered with gst_meta_api_type_register() which takes a -name for the metadata API and some tags associated with the metadata. -With gst_meta_api_type_has_tag() one can check if a certain metadata API -contains a given tag. - -Multiple implementations of a metadata API can be registered. -To implement a metadata API, gst_meta_register() should be used. This -function takes all parameters needed to create, free and transform metadata -along with the size of the metadata. The function returns a #GstMetaInfo -structure that contains the information for the implementation of the API. - -A specific implementation can be retrieved by name with gst_meta_get_info(). - -See #GstBuffer for how the metadata can be added, retrieved and removed from -buffers. - - - extra flags for the metadata - - - - pointer to the #GstMetaInfo - - - - Meta sequence number compare function. Can be used as #GCompareFunc -or a #GCompareDataFunc. - - - a negative number if @meta1 comes before @meta2, 0 if both metas - have an equal sequence number, or a positive integer if @meta1 comes - after @meta2. - - - - - a #GstMeta - - - - a #GstMeta - - - - - - Gets seqnum for this meta. - - - - - - - a #GstMeta - - - - - - - - an array of tags as strings. - - - - - - - an API - - - - - - Check if @api was registered with @tag. - - - %TRUE if @api was registered with @tag. - - - - - an API - - - - the tag to check - - - - - - Register and return a GType for the @api and associate it with -@tags. - - - a unique GType for @api. - - - - - an API to register - - - - tags for @api - - - - - - - - Lookup a previously registered meta info structure by its implementation name -@impl. - - - a #GstMetaInfo with @impl, or -%NULL when no such metainfo exists. - - - - - the name - - - - - - Register a new #GstMeta implementation. - -The same @info can be retrieved later with gst_meta_get_info() by using -@impl as the key. - - - a #GstMetaInfo that can be used to -access metadata. - - - - - the type of the #GstMeta API - - - - the name of the #GstMeta implementation - - - - the size of the #GstMeta structure - - - - a #GstMetaInitFunction - - - - a #GstMetaFreeFunction - - - - a #GstMetaTransformFunction - - - - - - - Extra metadata flags. - - no flags - - - metadata should not be modified - - - metadata is managed by a bufferpool - - - metadata should not be removed - - - additional flags can be added starting from this flag. - - - - Function called when @meta is freed in @buffer. - - - - - - - a #GstMeta - - - - a #GstBuffer - - - - - - The #GstMetaInfo provides information about a specific metadata -structure. - - - tag identifying the metadata structure and api - - - - type identifying the implementor of the api - - - - size of the metadata - - - - function for initializing the metadata - - - - function for freeing the metadata - - - - function for transforming the metadata - - - - - Function called when @meta is initialized in @buffer. - - - - - - - a #GstMeta - - - - parameters passed to the init function - - - - a #GstBuffer - - - - - - Extra data passed to a "gst-copy" transform #GstMetaTransformFunction. - - - %TRUE if only region is copied - - - - the offset to copy, 0 if @region is %FALSE, otherwise > 0 - - - - the size to copy, -1 or the buffer size when @region is %FALSE - - - - - Function called for each @meta in @buffer as a result of performing a -transformation on @transbuf. Additional @type specific transform data -is passed to the function as @data. - -Implementations should check the @type of the transform and parse -additional type specific fields in @data that should be used to update -the metadata on @transbuf. - - - %TRUE if the transform could be performed - - - - - a #GstBuffer - - - - a #GstMeta - - - - a #GstBuffer - - - - the transform type - - - - transform specific data. - - - - - - #GstMiniObject is a simple structure that can be used to implement refcounted -types. - -Subclasses will include #GstMiniObject as the first member in their structure -and then call gst_mini_object_init() to initialize the #GstMiniObject fields. - -gst_mini_object_ref() and gst_mini_object_unref() increment and decrement the -refcount respectively. When the refcount of a mini-object reaches 0, the -dispose function is called first and when this returns %TRUE, the free -function of the miniobject is called. - -A copy can be made with gst_mini_object_copy(). - -gst_mini_object_is_writable() will return %TRUE when the refcount of the -object is exactly 1 and there is no parent or a single parent exists and is -writable itself, meaning the current caller has the only reference to the -object. gst_mini_object_make_writable() will return a writable version of -the object, which might be a new copy when the refcount was not 1. - -Opaque data can be associated with a #GstMiniObject with -gst_mini_object_set_qdata() and gst_mini_object_get_qdata(). The data is -meant to be specific to the particular object and is not automatically copied -with gst_mini_object_copy() or similar methods. - -A weak reference can be added and remove with gst_mini_object_weak_ref() -and gst_mini_object_weak_unref() respectively. - - - the GType of the object - - - - atomic refcount - - - - atomic state of the locks - - - - extra flags. - - - - a copy function - - - - a dispose function - - - - the free function - - - - - - - - - - This adds @parent as a parent for @object. Having one ore more parents affects the -writability of @object: if a @parent is not writable, @object is also not -writable, regardless of its refcount. @object is only writable if all -the parents are writable and its own refcount is exactly 1. - -Note: This function does not take ownership of @parent and also does not -take an additional reference. It is the responsibility of the caller to -remove the parent again at a later time. - - - - - - - a #GstMiniObject - - - - a parent #GstMiniObject - - - - - - Creates a copy of the mini-object. - -MT safe - - - the new mini-object if copying is -possible, %NULL otherwise. - - - - - the mini-object to copy - - - - - - This function gets back user data pointers stored via -gst_mini_object_set_qdata(). - - - The user data pointer set, or -%NULL - - - - - The GstMiniObject to get a stored user data pointer from - - - - A #GQuark, naming the user data pointer - - - - - - Initializes a mini-object with the desired type and copy/dispose/free -functions. - - - - - - - a #GstMiniObject - - - - initial #GstMiniObjectFlags - - - - the #GType of the mini-object to create - - - - the copy function, or %NULL - - - - the dispose function, or %NULL - - - - the free function or %NULL - - - - - - If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE -lock on @object is the only one, this means that changes to the object will -not be visible to any other object. - -If the LOCKABLE flag is not set, check if the refcount of @mini_object is -exactly 1, meaning that no other reference exists to the object and that the -object is therefore writable. - -Modification of a mini-object should only be done after verifying that it -is writable. - - - %TRUE if the object is writable. - - - - - the mini-object to check - - - - - - Lock the mini-object with the specified access mode in @flags. - - - %TRUE if @object could be locked. - - - - - the mini-object to lock - - - - #GstLockFlags - - - - - - Checks if a mini-object is writable. If not, a writable copy is made and -returned. This gives away the reference to the original mini object, -and returns a reference to the new object. - -MT safe - - - a mini-object (possibly the same pointer) that - is writable. - - - - - the mini-object to make writable - - - - - - Increase the reference count of the mini-object. - -Note that the refcount affects the writability -of @mini-object, see gst_mini_object_is_writable(). It is -important to note that keeping additional references to -GstMiniObject instances can potentially increase the number -of memcpy operations in a pipeline, especially if the miniobject -is a #GstBuffer. - - - the mini-object. - - - - - the mini-object - - - - - - This removes @parent as a parent for @object. See -gst_mini_object_add_parent(). - - - - - - - a #GstMiniObject - - - - a parent #GstMiniObject - - - - - - This sets an opaque, named pointer on a miniobject. -The name is specified through a #GQuark (retrieved e.g. via -g_quark_from_static_string()), and the pointer -can be gotten back from the @object with gst_mini_object_get_qdata() -until the @object is disposed. -Setting a previously set user data pointer, overrides (frees) -the old pointer set, using %NULL as pointer essentially -removes the data stored. - -@destroy may be specified which is called with @data as argument -when the @object is disposed, or the data is being overwritten by -a call to gst_mini_object_set_qdata() with the same @quark. - - - - - - - a #GstMiniObject - - - - A #GQuark, naming the user data pointer - - - - An opaque user data pointer - - - - Function to invoke with @data as argument, when @data - needs to be freed - - - - - - This function gets back user data pointers stored via gst_mini_object_set_qdata() -and removes the data from @object without invoking its `destroy()` function (if -any was set). - - - The user data pointer set, or -%NULL - - - - - The GstMiniObject to get a stored user data pointer from - - - - A #GQuark, naming the user data pointer - - - - - - Unlock the mini-object with the specified access mode in @flags. - - - - - - - the mini-object to unlock - - - - #GstLockFlags - - - - - - Decreases the reference count of the mini-object, possibly freeing -the mini-object. - - - - - - - the mini-object - - - - - - Adds a weak reference callback to a mini object. Weak references are -used for notification when a mini object is finalized. They are called -"weak references" because they allow you to safely hold a pointer -to the mini object without calling gst_mini_object_ref() -(gst_mini_object_ref() adds a strong reference, that is, forces the object -to stay alive). - - - - - - - #GstMiniObject to reference weakly - - - - callback to invoke before the mini object is freed - - - - extra data to pass to notify - - - - - - Removes a weak reference callback from a mini object. - - - - - - - #GstMiniObject to remove a weak reference from - - - - callback to search for - - - - data to search for - - - - - - Atomically modifies a pointer to point to a new mini-object. -The reference count of @olddata is decreased and the reference count of -@newdata is increased. - -Either @newdata and the value pointed to by @olddata may be %NULL. - - - %TRUE if @newdata was different from @olddata - - - - - pointer to a pointer to a - mini-object to be replaced - - - - pointer to new mini-object - - - - - - Replace the current #GstMiniObject pointer to by @olddata with %NULL and -return the old value. - - - the #GstMiniObject at @oldata - - - - - pointer to a pointer to a mini-object to - be stolen - - - - - - Modifies a pointer to point to a new mini-object. The modification -is done atomically. This version is similar to gst_mini_object_replace() -except that it does not increase the refcount of @newdata and thus -takes ownership of @newdata. - -Either @newdata and the value pointed to by @olddata may be %NULL. - - - %TRUE if @newdata was different from @olddata - - - - - pointer to a pointer to a mini-object to - be replaced - - - - pointer to new mini-object - - - - - - - Function prototype for methods to create copies of instances. - - - reference to cloned instance. - - - - - MiniObject to copy - - - - - - Function prototype for when a miniobject has lost its last refcount. -Implementation of the mini object are allowed to revive the -passed object by doing a gst_mini_object_ref(). If the object is not -revived after the dispose function, the function should return %TRUE -and the memory associated with the object is freed. - - - %TRUE if the object should be cleaned up. - - - - - MiniObject to dispose - - - - - - Flags for the mini object - - the object can be locked and unlocked with -gst_mini_object_lock() and gst_mini_object_unlock(). - - - the object is permanently locked in -READONLY mode. Only read locks can be performed on the object. - - - the object is expected to stay alive -even after gst_deinit() has been called and so should be ignored by leak -detection tools. (Since: 1.10) - - - first flag that can be used by subclasses. - - - - Virtual function prototype for methods to free resources used by -mini-objects. - - - - - - - MiniObject to free - - - - - - A #GstMiniObjectNotify function can be added to a mini object as a -callback that gets triggered when gst_mini_object_unref() drops the -last ref and @obj is about to be freed. - - - - - - - data that was provided when the notify was added - - - - the mini object - - - - - - Constant that defines one GStreamer nanosecond - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This macro returns the entire set of flags for the object. - - - - a #GstObject - - - - - This macro checks to see if the given flag is set. - - - - a #GstObject - - - Flag to check for - - - - - This macro sets the given bits. - - - - a #GstObject - - - Flag to set - - - - - This macro unsets the given bits. - - - - a #GstObject - - - Flag to set - - - - - - - - - - - - Acquire a reference to the mutex of this object. - - - - a #GstObject - - - - - This macro will obtain a lock on the object, making serialization possible. -It blocks until the lock can be obtained. - - - - a #GstObject to lock - - - - - Get the name of this object. This is not thread-safe by default -(i.e. you will have to make sure the object lock is taken yourself). -If in doubt use gst_object_get_name() instead. - - - - a #GstObject - - - - - Get the parent of this object. This is not thread-safe by default -(i.e. you will have to make sure the object lock is taken yourself). -If in doubt use gst_object_get_parent() instead. - - - - a #GstObject - - - - - Get access to the reference count field of the object. - - - - a #GstObject - - - - - Get the reference count value of the object. - - - - a #GstObject - - - - - This macro will try to obtain a lock on the object, but will return with -%FALSE if it can't get it immediately. - - - - a #GstObject. - - - - - This macro releases a lock on the object. - - - - a #GstObject to unlock. - - - - - #GstObject provides a root for the object hierarchy tree filed in by the -GStreamer library. It is currently a thin wrapper on top of -#GInitiallyUnowned. It is an abstract class that is not very usable on its own. - -#GstObject gives us basic refcounting, parenting functionality and locking. -Most of the functions are just extended for special GStreamer needs and can be -found under the same name in the base class of #GstObject which is #GObject -(e.g. g_object_ref() becomes gst_object_ref()). - -Since #GstObject derives from #GInitiallyUnowned, it also inherits the -floating reference. Be aware that functions such as gst_bin_add() and -gst_element_add_pad() take ownership of the floating reference. - -In contrast to #GObject instances, #GstObject adds a name property. The functions -gst_object_set_name() and gst_object_get_name() are used to set/get the name -of the object. - -## controlled properties - -Controlled properties offers a lightweight way to adjust gobject properties -over stream-time. It works by using time-stamped value pairs that are queued -for element-properties. At run-time the elements continuously pull value -changes for the current stream-time. - -What needs to be changed in a #GstElement? -Very little - it is just two steps to make a plugin controllable! - - * mark gobject-properties paramspecs that make sense to be controlled, - by GST_PARAM_CONTROLLABLE. - - * when processing data (get, chain, loop function) at the beginning call - gst_object_sync_values(element,timestamp). - This will make the controller update all GObject properties that are - under its control with the current values based on the timestamp. - -What needs to be done in applications? Again it's not a lot to change. - - * create a #GstControlSource. - csource = gst_interpolation_control_source_new (); - g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - - * Attach the #GstControlSource on the controller to a property. - gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); - - * Set the control values - gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); - gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); - - * start your pipeline - - - Checks to see if there is any object named @name in @list. This function -does not do any locking of any kind. You might want to protect the -provided list with the lock of the owner of the list. This function -will lock each #GstObject in the list to compare the name, so be -careful when passing a list with a locked object. - - - %TRUE if a #GstObject named @name does not appear in @list, -%FALSE if it does. - -MT safe. Grabs and releases the LOCK of each object in the list. - - - - - a list of #GstObject to - check through - - - - - - the name to search for - - - - - - A default deep_notify signal callback for an object. The user data -should contain a pointer to an array of strings that should be excluded -from the notify. The default handler will print the new value of the property -using g_print. - -MT safe. This function grabs and releases @object's LOCK for getting its - path string. - - - - - - - the #GObject that signalled the notify. - - - - a #GstObject that initiated the notify. - - - - a #GParamSpec of the property. - - - - - a set of user-specified properties to exclude or %NULL to show - all changes. - - - - - - - - Increase the reference count of @object, and possibly remove the floating -reference, if @object has a floating reference. - -In other words, if the object is floating, then this call "assumes ownership" -of the floating reference, converting it to a normal reference by clearing -the floating flag while leaving the reference count unchanged. If the object -is not floating, then this call adds a new normal reference increasing the -reference count by one. - -For more background on "floating references" please see the #GObject -documentation. - - - - - - - a #GstObject to sink - - - - - - Atomically modifies a pointer to point to a new object. -The reference count of @oldobj is decreased and the reference count of -@newobj is increased. - -Either @newobj and the value pointed to by @oldobj may be %NULL. - - - %TRUE if @newobj was different from @oldobj - - - - - pointer to a place of - a #GstObject to replace - - - - a new #GstObject - - - - - - - - - - - - - - - - - - - - - - - Attach the #GstControlBinding to the object. If there already was a -#GstControlBinding for this property it will be replaced. - -The object's reference count will be incremented, and any floating -reference will be removed (see gst_object_ref_sink()) - - - %FALSE if the given @binding has not been setup for this object or -has been setup for a non suitable property, %TRUE otherwise. - - - - - the controller object - - - - the #GstControlBinding that should be used - - - - - - A default error function that uses g_printerr() to display the error message -and the optional debug string.. - -The default handler will simply print the error string using g_print. - - - - - - - the #GstObject that initiated the error. - - - - the GError. - - - - an additional debug information string, or %NULL - - - - - - Gets the corresponding #GstControlBinding for the property. This should be -unreferenced again after use. - - - the #GstControlBinding for -@property_name or %NULL if the property is not controlled. - - - - - the object - - - - name of the property - - - - - - Obtain the control-rate for this @object. Audio processing #GstElement -objects will use this rate to sub-divide their processing loop and call -gst_object_sync_values() in between. The length of the processing segment -should be up to @control-rate nanoseconds. - -If the @object is not under property control, this will return -%GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing. - -The control-rate is not expected to change if the element is in -%GST_STATE_PAUSED or %GST_STATE_PLAYING. - - - the control rate in nanoseconds - - - - - the object that has controlled properties - - - - - - Gets a number of #GValues for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -#GValue. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the object that has controlled properties - - - - the name of the property to get - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - - - Returns a copy of the name of @object. -Caller should g_free() the return value after usage. -For a nameless object, this returns %NULL, which you can safely g_free() -as well. - -Free-function: g_free - - - the name of @object. g_free() -after usage. - -MT safe. This function grabs and releases @object's LOCK. - - - - - a #GstObject - - - - - - Returns the parent of @object. This function increases the refcount -of the parent object so you should gst_object_unref() it after usage. - - - parent of @object, this can be - %NULL if @object has no parent. unref after usage. - -MT safe. Grabs and releases @object's LOCK. - - - - - a #GstObject - - - - - - Generates a string describing the path of @object in -the object hierarchy. Only useful (or used) for debugging. - -Free-function: g_free - - - a string describing the path of @object. You must - g_free() the string after usage. - -MT safe. Grabs and releases the #GstObject's LOCK for all objects - in the hierarchy. - - - - - a #GstObject - - - - - - Gets the value for the given controlled property at the requested time. - - - the GValue of the property at the given time, -or %NULL if the property isn't controlled. - - - - - the object that has controlled properties - - - - the name of the property to get - - - - the time the control-change should be read from - - - - - - Gets a number of values for the given controlled property starting at the -requested time. The array @values need to hold enough space for @n_values of -the same type as the objects property's type. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - -The values are unboxed and ready to be used. The similar function -gst_object_get_g_value_array() returns the array as #GValues and is -better suites for bindings. - - - %TRUE if the given array could be filled, %FALSE otherwise - - - - - the object that has controlled properties - - - - the name of the property to get - - - - the time that should be processed - - - - the time spacing between subsequent values - - - - the number of values - - - - array to put control-values in - - - - - - Check if the @object has active controlled properties. - - - %TRUE if the object has active controlled properties - - - - - the object that has controlled properties - - - - - - Check if @object has an ancestor @ancestor somewhere up in -the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. - Use gst_object_has_as_ancestor() instead. - -MT safe. Grabs and releases @object's locks. - - - %TRUE if @ancestor is an ancestor of @object. - - - - - a #GstObject to check - - - - a #GstObject to check as ancestor - - - - - - Check if @object has an ancestor @ancestor somewhere up in -the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. - - - %TRUE if @ancestor is an ancestor of @object. - -MT safe. Grabs and releases @object's locks. - - - - - a #GstObject to check - - - - a #GstObject to check as ancestor - - - - - - Check if @parent is the parent of @object. -E.g. a #GstElement can check if it owns a given #GstPad. - - - %FALSE if either @object or @parent is %NULL. %TRUE if @parent is - the parent of @object. Otherwise %FALSE. - -MT safe. Grabs and releases @object's locks. - - - - - a #GstObject to check - - - - a #GstObject to check as parent - - - - - - Increments the reference count on @object. This function -does not take the lock on @object because it relies on -atomic refcounting. - -This object returns the input parameter to ease writing -constructs like : - result = gst_object_ref (object->parent); - - - A pointer to @object - - - - - a #GstObject to reference - - - - - - Removes the corresponding #GstControlBinding. If it was the -last ref of the binding, it will be disposed. - - - %TRUE if the binding could be removed. - - - - - the object - - - - the binding - - - - - - This function is used to disable the control bindings on a property for -some time, i.e. gst_object_sync_values() will do nothing for the -property. - - - - - - - the object that has controlled properties - - - - property to disable - - - - boolean that specifies whether to disable the controller -or not. - - - - - - This function is used to disable all controlled properties of the @object for -some time, i.e. gst_object_sync_values() will do nothing. - - - - - - - the object that has controlled properties - - - - boolean that specifies whether to disable the controller -or not. - - - - - - Change the control-rate for this @object. Audio processing #GstElement -objects will use this rate to sub-divide their processing loop and call -gst_object_sync_values() in between. The length of the processing segment -should be up to @control-rate nanoseconds. - -The control-rate should not change if the element is in %GST_STATE_PAUSED or -%GST_STATE_PLAYING. - - - - - - - the object that has controlled properties - - - - the new control-rate in nanoseconds. - - - - - - Sets the name of @object, or gives @object a guaranteed unique -name (if @name is %NULL). -This function makes a copy of the provided name, so the caller -retains ownership of the name it sent. - - - %TRUE if the name could be set. Since Objects that have -a parent cannot be renamed, this function returns %FALSE in those -cases. - -MT safe. This function grabs and releases @object's LOCK. - - - - - a #GstObject - - - - new name of object - - - - - - Sets the parent of @object to @parent. The object's reference count will -be incremented, and any floating reference will be removed (see gst_object_ref_sink()). - - - %TRUE if @parent could be set or %FALSE when @object -already had a parent or @object and @parent are the same. - -MT safe. Grabs and releases @object's LOCK. - - - - - a #GstObject - - - - new parent of object - - - - - - Returns a suggestion for timestamps where buffers should be split -to get best controller results. - - - Returns the suggested timestamp or %GST_CLOCK_TIME_NONE -if no control-rate was set. - - - - - the object that has controlled properties - - - - - - Sets the properties of the object, according to the #GstControlSources that -(maybe) handle them and for the given timestamp. - -If this function fails, it is most likely the application developers fault. -Most probably the control sources are not setup correctly. - - - %TRUE if the controller values could be applied to the object -properties, %FALSE otherwise - - - - - the object that has controlled properties - - - - the time that should be processed - - - - - - Clear the parent of @object, removing the associated reference. -This function decreases the refcount of @object. - -MT safe. Grabs and releases @object's lock. - - - - - - - a #GstObject to unparent - - - - - - Decrements the reference count on @object. If reference count hits -zero, destroy @object. This function does not take the lock -on @object as it relies on atomic refcounting. - -The unref method should never be called with the LOCK held since -this might deadlock the dispose function. - - - - - - - a #GstObject to unreference - - - - - - - - - The parent of the object. Please note, that when changing the 'parent' -property, we don't emit #GObject::notify and #GstObject::deep-notify -signals due to locking issues. In some cases one can use -#GstBin::element-added or #GstBin::element-removed signals on the parent to -achieve a similar effect. - - - - - - - object LOCK - - - - The name of the object - - - - this object's parent, weak ref - - - - flags for this object - - - - - - - - - - - - - - - - - - The deep notify signal is used to be notified of property changes. It is -typically attached to the toplevel bin to receive notifications from all -the elements contained in that bin. - - - - - - the object that originated the signal - - - - the property that changed - - - - - - - GStreamer base object class. - - - parent - - - - separator used by gst_object_get_path_string() - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The standard flags that an gstobject may have. - - the object is expected to stay alive even -after gst_deinit() has been called and so should be ignored by leak -detection tools. (Since: 1.10) - - - subclasses can add additional flags starting from this flag - - - - - - - - - - - Get the #GstPadActivateFunction from @pad. - - - - a #GstPad - - - - - Get the #GstPadActivateModeFunction from the given @pad. - - - - a #GstPad - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the #GstPadChainFunction from the given @pad. - - - - a #GstPad - - - - - Get the #GstPadChainListFunction from the given @pad. - - - - a #GstPad - - - - - - - - - - - - Get the #GstPadDirection of the given @pad. Accessor macro, use -gst_pad_get_direction() instead. - - - - a #GstPad - - - - - Get the private data of @pad, which is usually some pad- or stream-specific -structure created by the element and set on the pad when creating it. -No locking is performed in this function. - - - - a #GstPad - - - - - Get the #GstPadEventFullFunction from the given @pad, which -is the function that handles events on the pad. You can -use this to set your own event handling function on a pad -after you create it. If your element derives from a base -class, use the base class's virtual functions instead. - - - - a #GstPad - - - - - Get the #GstPadEventFunction from the given @pad, which -is the function that handles events on the pad. You can -use this to set your own event handling function on a pad -after you create it. If your element derives from a base -class, use the base class's virtual functions instead. - - - - a #GstPad - - - - - Get the #GstPadGetRangeFunction from the given @pad. - - - - a #GstPad - - - - - Get the stream lock of @pad. The stream lock is protecting the -resources used in the data processing functions of @pad. Accessor -macro, use GST_PAD_STREAM_LOCK() and GST_PAD_STREAM_UNLOCK() instead -to take/release the pad's stream lock. - - - - a #GstPad - - - - - Check if the given @pad has pending events. This is used internally by -GStreamer. - - - - a #GstPad - - - - - Check if the pad's accept intersect flag is set. The default accept-caps -handler will check if the caps intersect the query-caps result instead of -checking for a subset. This is interesting for parser elements that can -accept incompletely specified caps. - - - - a #GstPad - - - - - Check if the pad's accept caps operation will use the pad template caps. -The default accept-caps will do a query caps to get the caps, which might -be querying downstream causing unnecessary overhead. It is recommended to -implement a proper accept-caps query handler or to use this flag to prevent -recursive accept-caps handling. - - - - a #GstPad - - - - - - - - a #GstPad - - - - - Check if the dataflow on a @pad is blocked. Use gst_pad_is_blocked() instead. - - - - a #GstPad - - - - - Check if the @pad is currently blocking on a buffer or event. Use -gst_pad_is_blocking() instead. - - - - a #GstPad - - - - - Check if the @pad is in EOS state. - - - - a #GstPad - - - - - Check if the given @pad is using fixed caps, which means that -once the caps are set on the @pad, the caps query function will -only return those caps. See gst_pad_use_fixed_caps(). - - - - a #GstPad - - - - - Check if the given @pad is flushing. - - - - a #GstPad - - - - - - - - a #GstPad - - - - - Check if the given @pad is set as proxy allocation which means -that the default query handler will forward allocation queries to the -internally linked @pads instead of discarding them. - - - - a #GstPad - - - - - Check if the given @pad is set to proxy caps. This means that the default -event and query handler will forward all events and queries to the -internally linked @pads instead of discarding them. - - - - a #GstPad - - - - - Check if the given @pad is set to proxy scheduling queries, which means that -the default query handler will forward scheduling queries to the internally -linked @pads instead of discarding them. - - - - a #GstPad - - - - - - - - a #GstPad - - - - - - - - a #GstPad - - - - - Get the #GstPadIterIntLinkFunction from the given @pad. - - - - a #GstPad - - - - - Gets the last flow return on this pad - - - - a #GstPad - - - - - Get the #GstPadLinkFunction for the given @pad. - - - - a #GstPad - - - - - Macro to test if the given #GstPadLinkReturn value indicates a failed -link step. - - - - the #GstPadLinkReturn value - - - - - Macro to test if the given #GstPadLinkReturn value indicates a successful -link step. - - - - the #GstPadLinkReturn value - - - - - Get the #GstPadMode of pad, which will be GST_PAD_MODE_NONE if the pad -has not been activated yet, and otherwise either GST_PAD_MODE_PUSH or -GST_PAD_MODE_PULL depending on which mode the pad was activated in. - - - - a #GstPad - - - - - Get name of the given pad. -No locking is performed in this function, use gst_pad_get_name() instead. - - - - a #GstPad - - - - - Check if there is a parent object before calling into the @pad callbacks. -This is used internally by GStreamer. - - - - a #GstPad - - - - - Check if the @pad should be reconfigured/renegotiated. -The flag has to be unset manually after reconfiguration happened. -Use gst_pad_needs_reconfigure() or gst_pad_check_reconfigure() instead. - - - - a #GstPad - - - - - Get the @pad #GstPadTemplate. It describes the possible media types -a @pad or an element factory can handle. - - - - a #GstPad - - - - - Get the @pad parent. -No locking is performed in this function, use gst_pad_get_parent() instead. - - - - a #GstPad - - - - - Return the pad's peer member. This member is a pointer to the linked @pad. -No locking is performed in this function, use gst_pad_get_peer() instead. - - - - a #GstPad - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the #GstPadQueryFunction from @pad, which is the function -that handles queries on the pad. You can use this to set your -own query handling function on a pad after you create it. If your -element derives from a base class, use the base class's virtual -functions instead. - - - - a #GstPad - - - - - Set @pad to by default accept caps by intersecting the result instead of -checking for a subset. This is interesting for parser elements that can -accept incompletely specified caps. - - - - a #GstPad - - - - - Set @pad to by default use the pad template caps to compare with -the accept caps instead of using a caps query result. - - - - a #GstPad - - - - - Set the given @pad to flushing state, which means it will not accept any -more events, queries or buffers, and return GST_FLOW_FLUSHING if any buffers -are pushed on it. This usually happens when the pad is shut down or when -a flushing seek happens. This is used inside GStreamer when flush start/stop -events pass through pads, or when an element state is changed and pads are -activated or deactivated. - - - - a #GstPad - - - - - Set @pad to proxy allocation queries, which means that the default query -handler will forward allocation queries to the internally linked @pads -instead of discarding them. -Set this if the element always outputs data in the exact same format as it -receives as input. This is just for convenience to avoid implementing some -standard query handling code in an element. - - - - a #GstPad - - - - - Set @pad to proxy caps, so that all caps-related events and queries are -proxied down- or upstream to the other side of the element automatically. -Set this if the element always outputs data in the exact same format as it -receives as input. This is just for convenience to avoid implementing some -standard event and query handling code in an element. - - - - a #GstPad - - - - - Set @pad to proxy scheduling queries, which means that the default query -handler will forward scheduling queries to the internally linked @pads -instead of discarding them. You will usually want to handle scheduling -queries explicitly if your element supports multiple scheduling modes. - - - - a #GstPad - - - - - Take the pad's stream lock. The stream lock is recursive and will be taken -when buffers or serialized downstream events are pushed on a pad. - - - - a #GstPad - - - - - Try to take the pad's stream lock, and return %TRUE if the lock could be -taken, and otherwise %FALSE. - - - - a #GstPad - - - - - Release the pad's stream lock. - - - - a #GstPad - - - - - Get the #GstTask of @pad. Accessor macro used by GStreamer. Use the -gst_pad_start_task(), gst_pad_stop_task() and gst_pad_pause_task() -functions instead. - - - - a #GstPad - - - - - - - - - - - - Get a handle to the padtemplate #GstCaps - - - - the template to query - - - - - - - - - - - - Get the #GstPadDirection of the padtemplate. - - - - the template to query - - - - - Get the #GType of the padtemplate - - - - the template to query - - - - - Check if the properties of the padtemplate are fixed - - - - the template to query - - - - - Get the nametemplate of the padtemplate. - - - - the template to query - - - - - Get the #GstPadPresence of the padtemplate. - - - - the template to query - - - - - Get the #GstPadUnlinkFunction from the given @pad. - - - - a #GstPad - - - - - Unset accept intersect flag. - - - - a #GstPad - - - - - Unset accept template flag. - - - - a #GstPad - - - - - Unset the flushing flag. - - - - a #GstPad - - - - - Unset proxy allocation flag. - - - - a #GstPad - - - - - Unset proxy caps flag. - - - - a #GstPad - - - - - Unset proxy scheduling flag. - - - - a #GstPad - - - - - Use this flag on GObject properties of GstObject to indicate that -they might not be available depending on environment such as OS, device, etc, -so such properties will be installed conditionally only if the GstObject is -able to support it. - - - - - Use this flag on GObject properties to signal they can make sense to be. -controlled over time. This hint is used by the GstController. - - - - - Use this flag on GObject properties of GstObject to indicate that -during `gst-inspect` and friends, the default value should be used -as default instead of the current value. - - - - - Use this flag on GObject properties of GstElements to indicate that -they can be changed when the element is in the PAUSED or lower state. -This flag implies GST_PARAM_MUTABLE_READY. - - - - - Use this flag on GObject properties of GstElements to indicate that -they can be changed when the element is in the PLAYING or lower state. -This flag implies GST_PARAM_MUTABLE_PAUSED. - - - - - Use this flag on GObject properties of GstElements to indicate that -they can be changed when the element is in the READY or lower state. - - - - - - - - - - - - - - - - - - - Bits based on GST_PARAM_USER_SHIFT can be used by 3rd party applications. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This macro needs to be used to define the entry point and meta data of a -plugin. One would use this macro to export a plugin, so that it can be used -by other applications. - -The macro uses a define named PACKAGE for the #GstPluginDesc,source field. -When using autoconf, this is usually set automatically via the AC_INIT -macro, and set in config.h. If you are not using autoconf, you will need to -define PACKAGE yourself and set it to a short mnemonic string identifying -your application/package, e.g. 'someapp' or 'my-plugins-foo. - -If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the -#GstPluginDesc,release_datetime field. - - - - major version number of the gstreamer-core that plugin was compiled for - - - minor version number of the gstreamer-core that plugin was compiled for - - - short, but unique name of the plugin - - - information about the purpose of the plugin - - - function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>. - - - full version string (e.g. VERSION from config.h) - - - under which licence the package has been released, e.g. GPL, LGPL. - - - the package-name (e.g. PACKAGE_NAME from config.h) - - - a description from where the package comes from (e.g. the homepage URL) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Debug the plugin feature names in @list. - - - - a #GList of - plugin features - - - - - - - - - - - - This macro can be used to initialize statically linked plugins. It is -necessary to call this macro before the plugin can be used. -It has to be used in combination with GST_PLUGIN_STATIC_REGISTER -and must be placed outside any block to declare the plugin initialization -function. - - - - short, but unique name of the plugin - - - - - This macro can be used to initialize statically linked plugins. It is -necessary to call this macro before the plugin can be used. -It has to be used in combination with GST_PLUGIN_STATIC_DECLARE and -calls the plugin initialization function. - - - - short, but unique name of the plugin - - - - - - - - - - - - - - - - - - - - - - - - - - The field name in a GstCaps that is used to signal the UUID of the protection -system. - - - - - The protection system value of the unspecified UUID. -In some cases the system protection ID is not present in the contents or in their -metadata, as encrypted WebM. -This define is used to set the value of the "system_id" field in GstProtectionEvent, -with this value, the application will use an external information to choose which -protection system to use. - -Example: The matroskademux uses this value in the case of encrypted WebM, -the application will choose the appropriate protection system based on the information -received through EME API. - - - - - - - - - - - - - - - - - - - printf format type used to debug GStreamer types. You can use this in -combination with GStreamer's debug logging system as well as the functions -gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() -to pretty-print the following types: #GstCaps, #GstStructure, -#GstCapsFeatures, #GstTagList, #GstDateTime, #GstBuffer, #GstBufferList, -#GstMessage, #GstEvent, #GstQuery, #GstContext, #GstPad, #GstObject. All -#GObject types will be printed as typename plus pointer, and everything -else will simply be printed as pointer address. - -This can only be used on types whose size is >= sizeof(gpointer). - - - - - A #GstElement is linked to other elements via "pads", which are extremely -light-weight generic link points. - -Pads have a #GstPadDirection, source pads produce data, sink pads consume -data. - -Pads are typically created from a #GstPadTemplate with -gst_pad_new_from_template() and are then added to a #GstElement. This usually -happens when the element is created but it can also happen dynamically based -on the data that the element is processing or based on the pads that the -application requests. - -Pads without pad templates can be created with gst_pad_new(), -which takes a direction and a name as an argument. If the name is %NULL, -then a guaranteed unique name will be assigned to it. - -A #GstElement creating a pad will typically use the various -gst_pad_set_*_function\() calls to register callbacks for events, queries or -dataflow on the pads. - -gst_pad_get_parent() will retrieve the #GstElement that owns the pad. - -After two pads are retrieved from an element by gst_element_get_static_pad(), -the pads can be linked with gst_pad_link(). (For quick links, -you can also use gst_element_link(), which will make the obvious -link for you if it's straightforward.). Pads can be unlinked again with -gst_pad_unlink(). gst_pad_get_peer() can be used to check what the pad is -linked to. - -Before dataflow is possible on the pads, they need to be activated with -gst_pad_set_active(). - -gst_pad_query() and gst_pad_peer_query() can be used to query various -properties of the pad and the stream. - -To send a #GstEvent on a pad, use gst_pad_send_event() and -gst_pad_push_event(). Some events will be sticky on the pad, meaning that -after they pass on the pad they can be queried later with -gst_pad_get_sticky_event() and gst_pad_sticky_events_foreach(). -gst_pad_get_current_caps() and gst_pad_has_current_caps() are convenience -functions to query the current sticky CAPS event on a pad. - -GstElements will use gst_pad_push() and gst_pad_pull_range() to push out -or pull in a buffer. - -The dataflow, events and queries that happen on a pad can be monitored with -probes that can be installed with gst_pad_add_probe(). gst_pad_is_blocked() -can be used to check if a block probe is installed on the pad. -gst_pad_is_blocking() checks if the blocking probe is currently blocking the -pad. gst_pad_remove_probe() is used to remove a previously installed probe -and unblock blocking probes if any. - -Pad have an offset that can be retrieved with gst_pad_get_offset(). This -offset will be applied to the running_time of all data passing over the pad. -gst_pad_set_offset() can be used to change the offset. - -Convenience functions exist to start, pause and stop the task on a pad with -gst_pad_start_task(), gst_pad_pause_task() and gst_pad_stop_task() -respectively. - - - Creates a new pad with the given name in the given direction. -If name is %NULL, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. - - - a new #GstPad. - -MT safe. - - - - - the name of the new pad. - - - - the #GstPadDirection of the pad. - - - - - - Creates a new pad with the given name from the given static template. -If name is %NULL, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. - - - a new #GstPad. - - - - - the #GstStaticPadTemplate to use - - - - the name of the pad - - - - - - Creates a new pad with the given name from the given template. -If name is %NULL, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. - - - a new #GstPad. - - - - - the pad template to use - - - - the name of the pad - - - - - - Gets a string representing the given pad-link return. - - - a static string with the name of the pad-link return. - - - - - a #GstPadLinkReturn to get the name of. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Activates or deactivates the given pad in @mode via dispatching to the -pad's activatemodefunc. For use from within pad activation functions only. - -If you don't know what this is, you probably don't want to call it. - - - %TRUE if the operation was successful. - -MT safe. - - - - - the #GstPad to activate or deactivate. - - - - the requested activation mode - - - - whether or not the pad should be active. - - - - - - Be notified of different states of pads. The provided callback is called for -every state that matches @mask. - -Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are -called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only -exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called -immediately if the pad is already idle while calling gst_pad_add_probe(). -In each of the groups, probes are called in the order in which they were -added. - - - an id or 0 if no probe is pending. The id can be used to remove the -probe with gst_pad_remove_probe(). When using GST_PAD_PROBE_TYPE_IDLE it can -happen that the probe can be run immediately and if the probe returns -GST_PAD_PROBE_REMOVE this functions returns 0. - -MT safe. - - - - - the #GstPad to add the probe to - - - - the probe mask - - - - #GstPadProbeCallback that will be called with notifications of - the pad state - - - - user data passed to the callback - - - - #GDestroyNotify for user_data - - - - - - Checks if the source pad and the sink pad are compatible so they can be -linked. - - - %TRUE if the pads can be linked. - - - - - the source #GstPad. - - - - the sink #GstPad. - - - - - - Chain a buffer to @pad. - -The function returns #GST_FLOW_FLUSHING if the pad was flushing. - -If the buffer type is not acceptable for @pad (as negotiated with a -preceding GST_EVENT_CAPS event), this function returns -#GST_FLOW_NOT_NEGOTIATED. - -The function proceeds calling the chain function installed on @pad (see -gst_pad_set_chain_function()) and the return value of that function is -returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no -chain function. - -In all cases, success or failure, the caller loses its reference to @buffer -after calling this function. - - - a #GstFlowReturn from the pad. - -MT safe. - - - - - a sink #GstPad, returns GST_FLOW_ERROR if not. - - - - the #GstBuffer to send, return GST_FLOW_ERROR - if not. - - - - - - Chain a bufferlist to @pad. - -The function returns #GST_FLOW_FLUSHING if the pad was flushing. - -If @pad was not negotiated properly with a CAPS event, this function -returns #GST_FLOW_NOT_NEGOTIATED. - -The function proceeds calling the chainlist function installed on @pad (see -gst_pad_set_chain_list_function()) and the return value of that function is -returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no -chainlist function. - -In all cases, success or failure, the caller loses its reference to @list -after calling this function. - -MT safe. - - - a #GstFlowReturn from the pad. - - - - - a sink #GstPad, returns GST_FLOW_ERROR if not. - - - - the #GstBufferList to send, return GST_FLOW_ERROR - if not. - - - - - - Check and clear the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE -if the flag was set. - - - %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on @pad. - - - - - the #GstPad to check - - - - - - Creates a stream-id for the source #GstPad @pad by combining the -upstream information with the optional @stream_id of the stream -of @pad. @pad must have a parent #GstElement and which must have zero -or one sinkpad. @stream_id can only be %NULL if the parent element -of @pad has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending @stream_id to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. - -Since stream IDs are sorted alphabetically, any numbers in the -stream ID should be printed with a fixed number of characters, -preceded by 0's, such as by using the format \%03u instead of \%u. - - - A stream-id for @pad. g_free() after usage. - - - - - A source #GstPad - - - - Parent #GstElement of @pad - - - - The stream-id - - - - - - Creates a stream-id for the source #GstPad @pad by combining the -upstream information with the optional @stream_id of the stream -of @pad. @pad must have a parent #GstElement and which must have zero -or one sinkpad. @stream_id can only be %NULL if the parent element -of @pad has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending @stream_id to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. - - - A stream-id for @pad. g_free() after usage. - - - - - A source #GstPad - - - - Parent #GstElement of @pad - - - - The stream-id - - - - parameters for the @stream_id format string - - - - - - Creates a stream-id for the source #GstPad @pad by combining the -upstream information with the optional @stream_id of the stream -of @pad. @pad must have a parent #GstElement and which must have zero -or one sinkpad. @stream_id can only be %NULL if the parent element -of @pad has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending @stream_id to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. - - - A stream-id for @pad. g_free() after usage. - - - - - A source #GstPad - - - - Parent #GstElement of @pad - - - - The stream-id - - - - parameters for the @stream_id format string - - - - - - Invokes the default event handler for the given pad. - -The EOS event will pause the task associated with @pad before it is forwarded -to all internally linked pads, - -The event is sent to all pads internally linked to @pad. This function -takes ownership of @event. - - - %TRUE if the event was sent successfully. - - - - - a #GstPad to call the default event handler on. - - - - the parent of @pad or %NULL - - - - the #GstEvent to handle. - - - - - - Calls @forward for all internally linked pads of @pad. This function deals with -dynamically changing internal pads and will make sure that the @forward -function is only called once for each pad. - -When @forward returns %TRUE, no further pads will be processed. - - - %TRUE if one of the dispatcher functions returned %TRUE. - - - - - a #GstPad - - - - a #GstPadForwardFunction - - - - user data passed to @forward - - - - - - Gets the capabilities of the allowed media types that can flow through -@pad and its peer. - -The allowed capabilities is calculated as the intersection of the results of -calling gst_pad_query_caps() on @pad and its peer. The caller owns a reference -on the resulting caps. - - - the allowed #GstCaps of the - pad link. Unref the caps when you no longer need it. This - function returns %NULL when @pad has no peer. - -MT safe. - - - - - a #GstPad. - - - - - - Gets the capabilities currently configured on @pad with the last -#GST_EVENT_CAPS event. - - - the current caps of the pad with -incremented ref-count or %NULL when pad has no caps. Unref after usage. - - - - - a #GstPad to get the current capabilities of. - - - - - - Gets the direction of the pad. The direction of the pad is -decided at construction time so this function does not take -the LOCK. - - - the #GstPadDirection of the pad. - -MT safe. - - - - - a #GstPad to get the direction of. - - - - - - Gets the private data of a pad. -No locking is performed in this function. - - - a #gpointer to the private data. - - - - - the #GstPad to get the private data of. - - - - - - Gets the #GstFlowReturn return from the last data passed by this pad. - - - - - - - the #GstPad - - - - - - Get the offset applied to the running time of @pad. @pad has to be a source -pad. - - - the offset. - - - - - a #GstPad - - - - - - Gets the template for @pad. - - - the #GstPadTemplate from which - this pad was instantiated, or %NULL if this pad has no - template. Unref after usage. - - - - - a #GstPad. - - - - - - Gets the capabilities for @pad's template. - - - the #GstCaps of this pad template. -Unref after usage. - - - - - a #GstPad to get the template capabilities from. - - - - - - Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or -its parent is not an element, return %NULL. - - - the parent of the pad. The -caller has a reference on the parent, so unref when you're finished -with it. - -MT safe. - - - - - a pad - - - - - - Gets the peer of @pad. This function refs the peer pad so -you need to unref it after use. - - - the peer #GstPad. Unref after usage. - -MT safe. - - - - - a #GstPad to get the peer of. - - - - - - When @pad is flushing this function returns #GST_FLOW_FLUSHING -immediately and @buffer is %NULL. - -Calls the getrange function of @pad, see #GstPadGetRangeFunction for a -description of a getrange function. If @pad has no getrange function -installed (see gst_pad_set_getrange_function()) this function returns -#GST_FLOW_NOT_SUPPORTED. - -If @buffer points to a variable holding %NULL, a valid new #GstBuffer will be -placed in @buffer when this function returns #GST_FLOW_OK. The new buffer -must be freed with gst_buffer_unref() after usage. - -When @buffer points to a variable that points to a valid #GstBuffer, the -buffer will be filled with the result data when this function returns -#GST_FLOW_OK. If the provided buffer is larger than @size, only -@size bytes will be filled in the result buffer and its size will be updated -accordingly. - -Note that less than @size bytes can be returned in @buffer when, for example, -an EOS condition is near or when @buffer is not large enough to hold @size -bytes. The caller should check the result buffer size to get the result size. - -When this function returns any other result value than #GST_FLOW_OK, @buffer -will be unchanged. - -This is a lowlevel function. Usually gst_pad_pull_range() is used. - - - a #GstFlowReturn from the pad. - -MT safe. - - - - - a src #GstPad, returns #GST_FLOW_ERROR if not. - - - - The start offset of the buffer - - - - The length of the buffer - - - - a pointer to hold the #GstBuffer, - returns #GST_FLOW_ERROR if %NULL. - - - - - - If there is a single internal link of the given pad, this function will -return it. Otherwise, it will return NULL. - - - a #GstPad, or %NULL if @pad has none -or more than one internal links. Unref returned pad with -gst_object_unref(). - - - - - the #GstPad to get the internal link of. - - - - - - Returns a new reference of the sticky event of type @event_type -from the event. - - - a #GstEvent of type -@event_type or %NULL when no event of @event_type was on -@pad. Unref after usage. - - - - - the #GstPad to get the event from. - - - - the #GstEventType that should be retrieved. - - - - the index of the event - - - - - - Returns the current #GstStream for the @pad, or %NULL if none has been -set yet, i.e. the pad has not received a stream-start event yet. - -This is a convenience wrapper around gst_pad_get_sticky_event() and -gst_event_parse_stream(). - - - the current #GstStream for @pad, or %NULL. - unref the returned stream when no longer needed. - - - - - A source #GstPad - - - - - - Returns the current stream-id for the @pad, or %NULL if none has been -set yet, i.e. the pad has not received a stream-start event yet. - -This is a convenience wrapper around gst_pad_get_sticky_event() and -gst_event_parse_stream_start(). - -The returned stream-id string should be treated as an opaque string, its -contents should not be interpreted. - - - a newly-allocated copy of the stream-id for - @pad, or %NULL. g_free() the returned string when no longer - needed. - - - - - A source #GstPad - - - - - - Get @pad task state. If no task is currently -set, #GST_TASK_STOPPED is returned. - - - The current state of @pad's task. - - - - - the #GstPad to get task state from - - - - - - Check if @pad has caps set on it with a #GST_EVENT_CAPS event. - - - %TRUE when @pad has caps associated with it. - - - - - a #GstPad to check - - - - - - Query if a pad is active - - - %TRUE if the pad is active. - -MT safe. - - - - - the #GstPad to query - - - - - - Checks if the pad is blocked or not. This function returns the -last requested state of the pad. It is not certain that the pad -is actually blocking at this point (see gst_pad_is_blocking()). - - - %TRUE if the pad is blocked. - -MT safe. - - - - - the #GstPad to query - - - - - - Checks if the pad is blocking or not. This is a guaranteed state -of whether the pad is actually blocking on a #GstBuffer or a #GstEvent. - - - %TRUE if the pad is blocking. - -MT safe. - - - - - the #GstPad to query - - - - - - Checks if a @pad is linked to another pad or not. - - - %TRUE if the pad is linked, %FALSE otherwise. - -MT safe. - - - - - pad to check - - - - - - Gets an iterator for the pads to which the given pad is linked to inside -of the parent element. - -Each #GstPad element yielded by the iterator will have its refcount increased, -so unref after use. - -Free-function: gst_iterator_free - - - a new #GstIterator of #GstPad - or %NULL when the pad does not have an iterator function - configured. Use gst_iterator_free() after usage. - - - - - the GstPad to get the internal links of. - - - - - - Iterate the list of pads to which the given pad is linked to inside of -the parent element. -This is the default handler, and thus returns an iterator of all of the -pads inside the parent element with opposite direction. - -The caller must free this iterator after use with gst_iterator_free(). - - - a #GstIterator of #GstPad, or %NULL if @pad -has no parent. Unref each returned pad with gst_object_unref(). - - - - - the #GstPad to get the internal links of. - - - - the parent of @pad or %NULL - - - - - - Links the source pad and the sink pad. - - - A result code indicating if the connection worked or - what went wrong. - -MT Safe. - - - - - the source #GstPad to link. - - - - the sink #GstPad to link. - - - - - - Links the source pad and the sink pad. - -This variant of #gst_pad_link provides a more granular control on the -checks being done when linking. While providing some considerable speedups -the caller of this method must be aware that wrong usage of those flags -can cause severe issues. Refer to the documentation of #GstPadLinkCheck -for more information. - -MT Safe. - - - A result code indicating if the connection worked or - what went wrong. - - - - - the source #GstPad to link. - - - - the sink #GstPad to link. - - - - the checks to validate when linking - - - - - - Links @src to @sink, creating any #GstGhostPad's in between as necessary. - -This is a convenience function to save having to create and add intermediate -#GstGhostPad's as required for linking across #GstBin boundaries. - -If @src or @sink pads don't have parent elements or do not share a common -ancestor, the link will fail. - - - whether the link succeeded. - - - - - a #GstPad - - - - a #GstPad - - - - - - Links @src to @sink, creating any #GstGhostPad's in between as necessary. - -This is a convenience function to save having to create and add intermediate -#GstGhostPad's as required for linking across #GstBin boundaries. - -If @src or @sink pads don't have parent elements or do not share a common -ancestor, the link will fail. - -Calling gst_pad_link_maybe_ghosting_full() with -@flags == %GST_PAD_LINK_CHECK_DEFAULT is the recommended way of linking -pads with safety checks applied. - - - whether the link succeeded. - - - - - a #GstPad - - - - a #GstPad - - - - some #GstPadLinkCheck flags - - - - - - Mark a pad for needing reconfiguration. The next call to -gst_pad_check_reconfigure() will return %TRUE after this call. - - - - - - - the #GstPad to mark - - - - - - Check the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE -if the flag was set. - - - %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on @pad. - - - - - the #GstPad to check - - - - - - Pause the task of @pad. This function will also wait until the -function executed by the task is finished if this function is not -called from the task function. - - - a %TRUE if the task could be paused or %FALSE when the pad -has no task. - - - - - the #GstPad to pause the task of - - - - - - Performs gst_pad_query() on the peer of @pad. - -The caller is responsible for both the allocation and deallocation of -the query structure. - - - %TRUE if the query could be performed. This function returns %FALSE -if @pad has no peer. - - - - - a #GstPad to invoke the peer query on. - - - - the #GstQuery to perform. - - - - - - Check if the peer of @pad accepts @caps. If @pad has no peer, this function -returns %TRUE. - - - %TRUE if the peer of @pad can accept the caps or @pad has no peer. - - - - - a #GstPad to check the peer of - - - - a #GstCaps to check on the pad - - - - - - Gets the capabilities of the peer connected to this pad. Similar to -gst_pad_query_caps(). - -When called on srcpads @filter contains the caps that -upstream could produce in the order preferred by upstream. When -called on sinkpads @filter contains the caps accepted by -downstream in the preferred order. @filter might be %NULL but -if it is not %NULL the returned caps will be a subset of @filter. - - - the caps of the peer pad with incremented -ref-count. When there is no peer pad, this function returns @filter or, -when @filter is %NULL, ANY caps. - - - - - a #GstPad to get the capabilities of. - - - - a #GstCaps filter, or %NULL. - - - - - - Queries the peer pad of a given sink pad to convert @src_val in @src_format -to @dest_format. - - - %TRUE if the query could be performed. - - - - - a #GstPad, on whose peer pad to invoke the convert query on. - Must be a sink pad. - - - - a #GstFormat to convert from. - - - - a value to convert. - - - - the #GstFormat to convert to. - - - - a pointer to the result. - - - - - - Queries the peer pad of a given sink pad for the total stream duration. - - - %TRUE if the query could be performed. - - - - - a #GstPad on whose peer pad to invoke the duration query on. - Must be a sink pad. - - - - the #GstFormat requested - - - - a location in which to store the total - duration, or %NULL. - - - - - - Queries the peer of a given sink pad for the stream position. - - - %TRUE if the query could be performed. - - - - - a #GstPad on whose peer to invoke the position query on. - Must be a sink pad. - - - - the #GstFormat requested - - - - a location in which to store the current - position, or %NULL. - - - - - - Checks if all internally linked pads of @pad accepts the caps in @query and -returns the intersection of the results. - -This function is useful as a default accept caps query function for an element -that can handle any stream format, but requires caps that are acceptable for -all opposite pads. - - - %TRUE if @query could be executed - - - - - a #GstPad to proxy. - - - - an ACCEPT_CAPS #GstQuery. - - - - - - Calls gst_pad_query_caps() for all internally linked pads of @pad and returns -the intersection of the results. - -This function is useful as a default caps query function for an element -that can handle any stream format, but requires all its pads to have -the same caps. Two such elements are tee and adder. - - - %TRUE if @query could be executed - - - - - a #GstPad to proxy. - - - - a CAPS #GstQuery. - - - - - - Pulls a @buffer from the peer pad or fills up a provided buffer. - -This function will first trigger the pad block signal if it was -installed. - -When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this -function returns the result of gst_pad_get_range() on the peer pad. -See gst_pad_get_range() for a list of return values and for the -semantics of the arguments of this function. - -If @buffer points to a variable holding %NULL, a valid new #GstBuffer will be -placed in @buffer when this function returns #GST_FLOW_OK. The new buffer -must be freed with gst_buffer_unref() after usage. When this function -returns any other result value, @buffer will still point to %NULL. - -When @buffer points to a variable that points to a valid #GstBuffer, the -buffer will be filled with the result data when this function returns -#GST_FLOW_OK. When this function returns any other result value, -@buffer will be unchanged. If the provided buffer is larger than @size, only -@size bytes will be filled in the result buffer and its size will be updated -accordingly. - -Note that less than @size bytes can be returned in @buffer when, for example, -an EOS condition is near or when @buffer is not large enough to hold @size -bytes. The caller should check the result buffer size to get the result size. - - - a #GstFlowReturn from the peer pad. - -MT safe. - - - - - a sink #GstPad, returns GST_FLOW_ERROR if not. - - - - The start offset of the buffer - - - - The length of the buffer - - - - a pointer to hold the #GstBuffer, returns - GST_FLOW_ERROR if %NULL. - - - - - - Pushes a buffer to the peer of @pad. - -This function will call installed block probes before triggering any -installed data probes. - -The function proceeds calling gst_pad_chain() on the peer pad and returns -the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will -be returned. - -In all cases, success or failure, the caller loses its reference to @buffer -after calling this function. - - - a #GstFlowReturn from the peer pad. - -MT safe. - - - - - a source #GstPad, returns #GST_FLOW_ERROR if not. - - - - the #GstBuffer to push returns GST_FLOW_ERROR - if not. - - - - - - Sends the event to the peer of the given pad. This function is -mainly used by elements to send events to their peer -elements. - -This function takes ownership of the provided event so you should -gst_event_ref() it if you want to reuse the event after this call. - - - %TRUE if the event was handled. - -MT safe. - - - - - a #GstPad to push the event to. - - - - the #GstEvent to send to the pad. - - - - - - Pushes a buffer list to the peer of @pad. - -This function will call installed block probes before triggering any -installed data probes. - -The function proceeds calling the chain function on the peer pad and returns -the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will -be returned. If the peer pad does not have any installed chainlist function -every group buffer of the list will be merged into a normal #GstBuffer and -chained via gst_pad_chain(). - -In all cases, success or failure, the caller loses its reference to @list -after calling this function. - - - a #GstFlowReturn from the peer pad. - -MT safe. - - - - - a source #GstPad, returns #GST_FLOW_ERROR if not. - - - - the #GstBufferList to push returns GST_FLOW_ERROR - if not. - - - - - - Dispatches a query to a pad. The query should have been allocated by the -caller via one of the type-specific allocation functions. The element that -the pad belongs to is responsible for filling the query with an appropriate -response, which should then be parsed with a type-specific query parsing -function. - -Again, the caller is responsible for both the allocation and deallocation of -the query structure. - -Please also note that some queries might need a running pipeline to work. - - - %TRUE if the query could be performed. - - - - - a #GstPad to invoke the default query on. - - - - the #GstQuery to perform. - - - - - - Check if the given pad accepts the caps. - - - %TRUE if the pad can accept the caps. - - - - - a #GstPad to check - - - - a #GstCaps to check on the pad - - - - - - Gets the capabilities this pad can produce or consume. -Note that this method doesn't necessarily return the caps set by sending a -gst_event_new_caps() - use gst_pad_get_current_caps() for that instead. -gst_pad_query_caps returns all possible caps a pad can operate with, using -the pad's CAPS query function, If the query fails, this function will return -@filter, if not %NULL, otherwise ANY. - -When called on sinkpads @filter contains the caps that -upstream could produce in the order preferred by upstream. When -called on srcpads @filter contains the caps accepted by -downstream in the preferred order. @filter might be %NULL but -if it is not %NULL the returned caps will be a subset of @filter. - -Note that this function does not return writable #GstCaps, use -gst_caps_make_writable() before modifying the caps. - - - the caps of the pad with incremented ref-count. - - - - - a #GstPad to get the capabilities of. - - - - suggested #GstCaps, or %NULL - - - - - - Queries a pad to convert @src_val in @src_format to @dest_format. - - - %TRUE if the query could be performed. - - - - - a #GstPad to invoke the convert query on. - - - - a #GstFormat to convert from. - - - - a value to convert. - - - - the #GstFormat to convert to. - - - - a pointer to the result. - - - - - - Invokes the default query handler for the given pad. -The query is sent to all pads internally linked to @pad. Note that -if there are many possible sink pads that are internally linked to -@pad, only one will be sent the query. -Multi-sinkpad elements should implement custom query handlers. - - - %TRUE if the query was performed successfully. - - - - - a #GstPad to call the default query handler on. - - - - the parent of @pad or %NULL - - - - the #GstQuery to handle. - - - - - - Queries a pad for the total stream duration. - - - %TRUE if the query could be performed. - - - - - a #GstPad to invoke the duration query on. - - - - the #GstFormat requested - - - - a location in which to store the total - duration, or %NULL. - - - - - - Queries a pad for the stream position. - - - %TRUE if the query could be performed. - - - - - a #GstPad to invoke the position query on. - - - - the #GstFormat requested - - - - A location in which to store the current position, or %NULL. - - - - - - Remove the probe with @id from @pad. - -MT safe. - - - - - - - the #GstPad with the probe - - - - the probe id to remove - - - - - - Sends the event to the pad. This function can be used -by applications to send events in the pipeline. - -If @pad is a source pad, @event should be an upstream event. If @pad is a -sink pad, @event should be a downstream event. For example, you would not -send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream. -Furthermore, some downstream events have to be serialized with data flow, -like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If -the event needs to be serialized with data flow, this function will take the -pad's stream lock while calling its event function. - -To find out whether an event type is upstream, downstream, or downstream and -serialized, see #GstEventTypeFlags, gst_event_type_get_flags(), -#GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and -#GST_EVENT_IS_SERIALIZED. Note that in practice that an application or -plugin doesn't need to bother itself with this information; the core handles -all necessary locks and checks. - -This function takes ownership of the provided event so you should -gst_event_ref() it if you want to reuse the event after this call. - - - %TRUE if the event was handled. - - - - - a #GstPad to send the event to. - - - - the #GstEvent to send to the pad. - - - - - - Sets the given activate function for @pad. The activate function will -dispatch to gst_pad_activate_mode() to perform the actual activation. -Only makes sense to set on sink pads. - -Call this function if your sink pad can start a pull-based task. - - - - - - - a #GstPad. - - - - the #GstPadActivateFunction to set. - - - - user_data passed to @notify - - - - notify called when @activate will not be used anymore. - - - - - - Sets the given activate_mode function for the pad. An activate_mode function -prepares the element for data passing. - - - - - - - a #GstPad. - - - - the #GstPadActivateModeFunction to set. - - - - user_data passed to @notify - - - - notify called when @activatemode will not be used anymore. - - - - - - Activates or deactivates the given pad. -Normally called from within core state change functions. - -If @active, makes sure the pad is active. If it is already active, either in -push or pull mode, just return. Otherwise dispatches to the pad's activate -function to perform the actual activation. - -If not @active, calls gst_pad_activate_mode() with the pad's current mode -and a %FALSE argument. - - - %TRUE if the operation was successful. - -MT safe. - - - - - the #GstPad to activate or deactivate. - - - - whether or not the pad should be active. - - - - - - Sets the given chain function for the pad. The chain function is called to -process a #GstBuffer input buffer. see #GstPadChainFunction for more details. - - - - - - - a sink #GstPad. - - - - the #GstPadChainFunction to set. - - - - user_data passed to @notify - - - - notify called when @chain will not be used anymore. - - - - - - Sets the given chain list function for the pad. The chainlist function is -called to process a #GstBufferList input buffer list. See -#GstPadChainListFunction for more details. - - - - - - - a sink #GstPad. - - - - the #GstPadChainListFunction to set. - - - - user_data passed to @notify - - - - notify called when @chainlist will not be used anymore. - - - - - - Set the given private data gpointer on the pad. -This function can only be used by the element that owns the pad. -No locking is performed in this function. - - - - - - - the #GstPad to set the private data of. - - - - The private data to attach to the pad. - - - - - - Sets the given event handler for the pad. - - - - - - - a #GstPad of either direction. - - - - the #GstPadEventFullFunction to set. - - - - user_data passed to @notify - - - - notify called when @event will not be used anymore. - - - - - - Sets the given event handler for the pad. - - - - - - - a #GstPad of either direction. - - - - the #GstPadEventFunction to set. - - - - user_data passed to @notify - - - - notify called when @event will not be used anymore. - - - - - - Sets the given getrange function for the pad. The getrange function is -called to produce a new #GstBuffer to start the processing pipeline. see -#GstPadGetRangeFunction for a description of the getrange function. - - - - - - - a source #GstPad. - - - - the #GstPadGetRangeFunction to set. - - - - user_data passed to @notify - - - - notify called when @get will not be used anymore. - - - - - - Sets the given internal link iterator function for the pad. - - - - - - - a #GstPad of either direction. - - - - the #GstPadIterIntLinkFunction to set. - - - - user_data passed to @notify - - - - notify called when @iterintlink will not be used anymore. - - - - - - Sets the given link function for the pad. It will be called when -the pad is linked with another pad. - -The return value #GST_PAD_LINK_OK should be used when the connection can be -made. - -The return value #GST_PAD_LINK_REFUSED should be used when the connection -cannot be made for some reason. - -If @link is installed on a source pad, it should call the #GstPadLinkFunction -of the peer sink pad, if present. - - - - - - - a #GstPad. - - - - the #GstPadLinkFunction to set. - - - - user_data passed to @notify - - - - notify called when @link will not be used anymore. - - - - - - Set the offset that will be applied to the running time of @pad. - - - - - - - a #GstPad - - - - the offset - - - - - - Set the given query function for the pad. - - - - - - - a #GstPad of either direction. - - - - the #GstPadQueryFunction to set. - - - - user_data passed to @notify - - - - notify called when @query will not be used anymore. - - - - - - Sets the given unlink function for the pad. It will be called -when the pad is unlinked. - -Note that the pad's lock is already held when the unlink -function is called, so most pad functions cannot be called -from within the callback. - - - - - - - a #GstPad. - - - - the #GstPadUnlinkFunction to set. - - - - user_data passed to @notify - - - - notify called when @unlink will not be used anymore. - - - - - - Starts a task that repeatedly calls @func with @user_data. This function -is mostly used in pad activation functions to start the dataflow. -The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired -before @func is called. - - - a %TRUE if the task could be started. - - - - - the #GstPad to start the task of - - - - the task function to call - - - - user data passed to the task function - - - - called when @user_data is no longer referenced - - - - - - Iterates all sticky events on @pad and calls @foreach_func for every -event. If @foreach_func returns %FALSE the iteration is immediately stopped. - - - - - - - the #GstPad that should be used for iteration. - - - - the #GstPadStickyEventsForeachFunction that - should be called for every event. - - - - the optional user data. - - - - - - Stop the task of @pad. This function will also make sure that the -function executed by the task will effectively stop if not called -from the GstTaskFunction. - -This function will deadlock if called from the GstTaskFunction of -the task. Use gst_task_pause() instead. - -Regardless of whether the pad has a task, the stream lock is acquired and -released so as to ensure that streaming through this pad has finished. - - - a %TRUE if the task could be stopped or %FALSE on error. - - - - - the #GstPad to stop the task of - - - - - - Store the sticky @event on @pad - - - #GST_FLOW_OK on success, #GST_FLOW_FLUSHING when the pad -was flushing or #GST_FLOW_EOS when the pad was EOS. - - - - - a #GstPad - - - - a #GstEvent - - - - - - Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked -signal on both pads. - - - %TRUE if the pads were unlinked. This function returns %FALSE if -the pads were not linked together. - -MT safe. - - - - - the source #GstPad to unlink. - - - - the sink #GstPad to unlink. - - - - - - A helper function you can use that sets the FIXED_CAPS flag -This way the default CAPS query will always return the negotiated caps -or in case the pad is not negotiated, the padtemplate caps. - -The negotiated caps are the caps of the last CAPS event that passed on the -pad. Use this function on a pad that, once it negotiated to a CAPS, cannot -be renegotiated to something else. - - - - - - - the pad to use - - - - - - - - - - - - The offset that will be applied to the running time of the pad. - - - - - - - - - - private data owned by the parent element - - - - padtemplate for this pad - - - - the direction of the pad, cannot change after creating - the pad. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Signals that a pad has been linked to the peer pad. - - - - - - the peer pad that has been connected - - - - - - Signals that a pad has been unlinked from the peer pad. - - - - - - the peer pad that has been disconnected - - - - - - - This function is called when the pad is activated during the element -READY to PAUSED state change. By default this function will call the -activate function that puts the pad in push mode but elements can -override this function to activate the pad in pull mode if they wish. - - - %TRUE if the pad could be activated. - - - - - a #GstPad - - - - the parent of @pad - - - - - - The prototype of the push and pull activate functions. - - - %TRUE if the pad could be activated or deactivated. - - - - - a #GstPad - - - - the parent of @pad - - - - the requested activation mode of @pad - - - - activate or deactivate the pad. - - - - - - A function that will be called on sinkpads when chaining buffers. -The function typically processes the data contained in the buffer and -either consumes the data or passes it on to the internally linked pad(s). - -The implementer of this function receives a refcount to @buffer and should -gst_buffer_unref() when the buffer is no longer needed. - -When a chain function detects an error in the data stream, it must post an -error on the bus and return an appropriate #GstFlowReturn value. - - - #GST_FLOW_OK for success - - - - - the sink #GstPad that performed the chain. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the #GstBuffer that is chained, not %NULL. - - - - - - A function that will be called on sinkpads when chaining buffer lists. -The function typically processes the data contained in the buffer list and -either consumes the data or passes it on to the internally linked pad(s). - -The implementer of this function receives a refcount to @list and -should gst_buffer_list_unref() when the list is no longer needed. - -When a chainlist function detects an error in the data stream, it must -post an error on the bus and return an appropriate #GstFlowReturn value. - - - #GST_FLOW_OK for success - - - - - the sink #GstPad that performed the chain. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the #GstBufferList that is chained, not %NULL. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The direction of a pad. - - direction is unknown. - - - the pad is a source pad. - - - the pad is a sink pad. - - - - Function signature to handle an event for the pad. - -This variant is for specific elements that will take into account the -last downstream flow return (from a pad push), in which case they can -return it. - - - %GST_FLOW_OK if the event was handled properly, or any other -#GstFlowReturn dependent on downstream state. - - - - - the #GstPad to handle the event. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the #GstEvent to handle. - - - - - - Function signature to handle an event for the pad. - - - %TRUE if the pad could handle the event. - - - - - the #GstPad to handle the event. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the #GstEvent to handle. - - - - - - Pad state flags - - is dataflow on a pad blocked - - - is pad flushing - - - is pad in EOS state - - - is pad currently blocking on a buffer or event - - - ensure that there is a parent object before calling - into the pad callbacks. - - - the pad should be reconfigured/renegotiated. - The flag has to be unset manually after - reconfiguration happened. - - - the pad has pending events - - - the pad is using fixed caps. This means that - once the caps are set on the pad, the default caps query function - will only return those caps. - - - the default event and query handler will forward - all events and queries to the internally linked pads - instead of discarding them. - - - the default query handler will forward - allocation queries to the internally linked pads - instead of discarding them. - - - the default query handler will forward - scheduling queries to the internally linked pads - instead of discarding them. - - - the default accept-caps handler will check - it the caps intersect the query-caps result instead - of checking for a subset. This is interesting for - parsers that can accept incompletely specified caps. - - - the default accept-caps handler will use - the template pad caps instead of query caps to - compare with the accept caps. Use this in combination - with %GST_PAD_FLAG_ACCEPT_INTERSECT. (Since: 1.6) - - - offset to define more flags - - - - A forward function is called for all internally linked pads, see -gst_pad_forward(). - - - %TRUE if the dispatching procedure has to be stopped. - - - - - the #GstPad that is forwarded. - - - - the gpointer to optional user data. - - - - - - This function will be called on source pads when a peer element -request a buffer at the specified @offset and @length. If this function -returns #GST_FLOW_OK, the result buffer will be stored in @buffer. The -contents of @buffer is invalid for any other return value. - -This function is installed on a source pad with -gst_pad_set_getrange_function() and can only be called on source pads after -they are successfully activated with gst_pad_activate_mode() with the -#GST_PAD_MODE_PULL. - -@offset and @length are always given in byte units. @offset must normally be a value -between 0 and the length in bytes of the data available on @pad. The -length (duration in bytes) can be retrieved with a #GST_QUERY_DURATION or with a -#GST_QUERY_SEEKING. - -Any @offset larger or equal than the length will make the function return -#GST_FLOW_EOS, which corresponds to EOS. In this case @buffer does not -contain a valid buffer. - -The buffer size of @buffer will only be smaller than @length when @offset is -near the end of the stream. In all other cases, the size of @buffer must be -exactly the requested size. - -It is allowed to call this function with a 0 @length and valid @offset, in -which case @buffer will contain a 0-sized buffer and the function returns -#GST_FLOW_OK. - -When this function is called with a -1 @offset, the sequentially next buffer -of length @length in the stream is returned. - -When this function is called with a -1 @length, a buffer with a default -optimal length is returned in @buffer. The length might depend on the value -of @offset. - - - #GST_FLOW_OK for success and a valid buffer in @buffer. Any other -return value leaves @buffer undefined. - - - - - the src #GstPad to perform the getrange on. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the offset of the range - - - - the length of the range - - - - a memory location to hold the result buffer, cannot be %NULL. - - - - - - The signature of the internal pad link iterator function. - - - a new #GstIterator that will iterate over all pads that are -linked to the given pad on the inside of the parent element. - -the caller must call gst_iterator_free() after usage. - - - - - The #GstPad to query. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - - - The amount of checking to be done when linking pads. @GST_PAD_LINK_CHECK_CAPS -and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are -specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed. - -> Only disable some of the checks if you are 100% certain you know the link -> will not fail because of hierarchy/caps compatibility failures. If uncertain, -> use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods -> for linking the pads. - - Don't check hierarchy or caps compatibility. - - - Check the pads have same parents/grandparents. - Could be omitted if it is already known that the two elements that own the - pads are in the same bin. - - - Check if the pads are compatible by using - their template caps. This is much faster than @GST_PAD_LINK_CHECK_CAPS, but - would be unsafe e.g. if one pad has %GST_CAPS_ANY. - - - Check if the pads are compatible by comparing the - caps returned by gst_pad_query_caps(). - - - Disables pushing a reconfigure event when pads are - linked. - - - The default checks done when linking - pads (i.e. the ones used by gst_pad_link()). - - - - Function signature to handle a new link on the pad. - - - the result of the link with the specified peer. - - - - - the #GstPad that is linked. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the peer #GstPad of the link - - - - - - Result values from gst_pad_link and friends. - - link succeeded - - - pads have no common grandparent - - - pad was already linked - - - pads have wrong direction - - - pads do not have common format - - - pads cannot cooperate in scheduling - - - refused for some reason - - - - The status of a GstPad. After activating a pad, which usually happens when the -parent element goes from READY to PAUSED, the GstPadMode defines if the -pad operates in push or pull mode. - - Pad will not handle dataflow - - - Pad handles dataflow in downstream push mode - - - Pad handles dataflow in upstream pull mode - - - Return the name of a pad mode, for use in debug messages mostly. - - - short mnemonic for pad mode @mode - - - - - the pad mode - - - - - - - Indicates when this pad will become available. - - the pad is always available - - - the pad will become available depending on the media stream - - - the pad is only available on request with - gst_element_request_pad(). - - - - - - - Callback used by gst_pad_add_probe(). Gets called to notify about the current -blocking type. - -The callback is allowed to modify the data pointer in @info. - - - a #GstPadProbeReturn - - - - - the #GstPad that is blocked - - - - #GstPadProbeInfo - - - - the gpointer to optional user data. - - - - - - Info passed in the #GstPadProbeCallback. - - - the current probe type - - - - the id of the probe - - - - type specific data, check the @type field to know the - datatype. This field can be %NULL. - - - - offset of pull probe, this field is valid when @type contains - #GST_PAD_PROBE_TYPE_PULL - - - - size of pull probe, this field is valid when @type contains - #GST_PAD_PROBE_TYPE_PULL - - - - - - - - - - - - - - - - - - - - The #GstBuffer from the probe - - - - - a #GstPadProbeInfo - - - - - - - - The #GstBufferList from the probe - - - - - a #GstPadProbeInfo - - - - - - - - The #GstEvent from the probe - - - - - a #GstPadProbeInfo - - - - - - - - The #GstQuery from the probe - - - - - a #GstPadProbeInfo - - - - - - - Different return values for the #GstPadProbeCallback. - - drop data in data probes. For push mode this means that - the data item is not sent downstream. For pull mode, it means that - the data item is not passed upstream. In both cases, no other probes - are called for this item and %GST_FLOW_OK or %TRUE is returned to the - caller. - - - normal probe return value. This leaves the probe in - place, and defers decisions about dropping or passing data to other - probes, if any. If there are no other probes, the default behaviour - for the probe type applies ('block' for blocking probes, - and 'pass' for non-blocking probes). - - - remove this probe. - - - pass the data item in the block probe and block on the - next item. - - - Data has been handled in the probe and will not be - forwarded further. For events and buffers this is the same behaviour as - %GST_PAD_PROBE_DROP (except that in this case you need to unref the buffer - or event yourself). For queries it will also return %TRUE to the caller. - The probe can also modify the #GstFlowReturn value by using the - #GST_PAD_PROBE_INFO_FLOW_RETURN() accessor. - Note that the resulting query must contain valid entries. - Since: 1.6 - - - - The different probing types that can occur. When either one of -@GST_PAD_PROBE_TYPE_IDLE or @GST_PAD_PROBE_TYPE_BLOCK is used, the probe will be a -blocking probe. - - invalid probe type - - - probe idle pads and block while the callback is called - - - probe and block pads - - - probe buffers - - - probe buffer lists - - - probe downstream events - - - probe upstream events - - - probe flush events. This probe has to be - explicitly enabled and is not included in the - @@GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM or - @@GST_PAD_PROBE_TYPE_EVENT_UPSTREAM probe types. - - - probe downstream queries - - - probe upstream queries - - - probe push - - - probe pull - - - probe and block at the next opportunity, at data flow or when idle - - - probe downstream data (buffers, buffer lists, and events) - - - probe upstream data (events) - - - probe upstream and downstream data (buffers, buffer lists, and events) - - - probe and block downstream data (buffers, buffer lists, and events) - - - probe and block upstream data (events) - - - probe upstream and downstream events - - - probe upstream and downstream queries - - - probe upstream events and queries and downstream buffers, buffer lists, events and queries - - - probe push and pull - - - - The signature of the query function. - - - %TRUE if the query could be performed. - - - - - the #GstPad to query. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - the #GstQuery object to execute - - - - - - Callback used by gst_pad_sticky_events_foreach(). - -When this function returns %TRUE, the next event will be -returned. When %FALSE is returned, gst_pad_sticky_events_foreach() will return. - -When @event is set to %NULL, the item will be removed from the list of sticky events. -@event can be replaced by assigning a new reference to it. -This function is responsible for unreffing the old event when -removing or modifying. - - - %TRUE if the iteration should continue - - - - - the #GstPad. - - - - a sticky #GstEvent. - - - - the #gpointer to optional user data. - - - - - - Padtemplates describe the possible media types a pad or an elementfactory can -handle. This allows for both inspection of handled types before loading the -element plugin as well as identifying pads on elements that are not yet -created (request or sometimes pads). - -Pad and PadTemplates have #GstCaps attached to it to describe the media type -they are capable of dealing with. gst_pad_template_get_caps() or -GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not -possible to modify the caps of a padtemplate after creation. - -PadTemplates have a #GstPadPresence property which identifies the lifetime -of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also -the direction of the pad can be retrieved from the #GstPadTemplate with -GST_PAD_TEMPLATE_DIRECTION(). - -The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads -because it has to be used as the name in the gst_element_get_request_pad() -call to instantiate a pad from this template. - -Padtemplates can be created with gst_pad_template_new() or with -gst_static_pad_template_get (), which creates a #GstPadTemplate from a -#GstStaticPadTemplate that can be filled with the -convenient GST_STATIC_PAD_TEMPLATE() macro. - -A padtemplate can be used to create a pad (see gst_pad_new_from_template() -or gst_pad_new_from_static_template ()) or to add to an element class -(see gst_element_class_add_static_pad_template ()). - -The following code example shows the code to create a pad from a padtemplate. -|[<!-- language="C" --> - GstStaticPadTemplate my_template = - GST_STATIC_PAD_TEMPLATE ( - "sink", // the name of the pad - GST_PAD_SINK, // the direction of the pad - GST_PAD_ALWAYS, // when this pad will be present - GST_STATIC_CAPS ( // the capabilities of the padtemplate - "audio/x-raw, " - "channels = (int) [ 1, 6 ]" - ) - ); - void - my_method (void) - { - GstPad *pad; - pad = gst_pad_new_from_static_template (&amp;my_template, "sink"); - ... - } -]| - -The following example shows you how to add the padtemplate to an -element class, this is usually done in the class_init of the class: -|[<!-- language="C" --> - static void - my_element_class_init (GstMyElementClass *klass) - { - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - - gst_element_class_add_static_pad_template (gstelement_class, &amp;my_template); - } -]| - - - Creates a new pad template with a name according to the given template -and with the given arguments. - - - a new #GstPadTemplate. - - - - - the name template. - - - - the #GstPadDirection of the template. - - - - the #GstPadPresence of the pad. - - - - a #GstCaps set for the template. - - - - - - Converts a #GstStaticPadTemplate into a #GstPadTemplate with a type. - - - a new #GstPadTemplate. - - - - - the static pad template - - - - The #GType of the pad to create - - - - - - Creates a new pad template with a name according to the given template -and with the given arguments. - - - a new #GstPadTemplate. - - - - - the name template. - - - - the #GstPadDirection of the template. - - - - the #GstPadPresence of the pad. - - - - a #GstCaps set for the template. - - - - The #GType of the pad to create - - - - - - Emit the pad-created signal for this template when created by this pad. - - - - - - - a #GstPadTemplate that has been created - - - - the #GstPad that created it - - - - - - Gets the capabilities of the pad template. - - - the #GstCaps of the pad template. -Unref after usage. - - - - - a #GstPadTemplate to get capabilities of. - - - - - - See gst_pad_template_set_documentation_caps(). - - - The caps to document. For convenience, this will return - gst_pad_template_get_caps() when no documentation caps were set. - - - - - the pad template to get documented capabilities on - - - - - - Emit the pad-created signal for this template when created by this pad. - - - - - - - a #GstPadTemplate that has been created - - - - the #GstPad that created it - - - - - - Certain elements will dynamically construct the caps of their -pad templates. In order not to let environment-specific information -into the documentation, element authors should use this method to -expose "stable" caps to the reader. - - - - - - - the pad template to set documented capabilities on - - - - the documented capabilities - - - - - - The capabilities of the pad described by the pad template. - - - - The direction of the pad described by the pad template. - - - - The type of the pad described by the pad template. - - - - The name template of the pad template. - - - - When the pad described by the pad template will become available. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This signal is fired when an element creates a pad from this template. - - - - - - the pad that was created. - - - - - - - - - - - - - - - - - - - a #GstPadTemplate that has been created - - - - the #GstPad that created it - - - - - - - - - - - - - Flags for the padtemplate - - first flag that can be used by subclasses. - - - - Function signature to handle a unlinking the pad prom its peer. - -The pad's lock is already held when the unlink function is called, so most -pad functions cannot be called from within the callback. - - - - - - - the #GstPad that is linked. - - - - the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT - flag is set, @parent is guaranteed to be not-%NULL and remain valid - during the execution of this function. - - - - - - A fundamental type that describes a #GParamSpec for arrays of -values - - - A fundamental type that describes a #GParamSpec for fractional -properties - - - A GParamSpec derived structure for arrays of values. - - - super class - - - - the #GParamSpec of the type of values in the array - - - - - A GParamSpec derived structure that contains the meta data for fractional -properties. - - - super class - - - - minimal numerator - - - - minimal denominator - - - - maximal numerator - - - - maximal denominator - - - - default numerator - - - - default denominator - - - - - The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer -to hold a reference to another buffer that is only released when the child -#GstBuffer is released. - -Typically, #GstParentBufferMeta is used when the child buffer is directly -using the #GstMemory of the parent buffer, and wants to prevent the parent -buffer from being returned to a buffer pool until the #GstMemory is available -for re-use. - - - the parent #GstMeta structure - - - - the #GstBuffer on which a reference is being held. - - - - Get the global #GstMetaInfo describing the #GstParentBufferMeta meta. - - - The #GstMetaInfo - - - - - - Opaque structure. - - - Allocates a parse context for use with gst_parse_launch_full() or -gst_parse_launchv_full(). - -Free-function: gst_parse_context_free - - - a newly-allocated parse context. Free - with gst_parse_context_free() when no longer needed. - - - - - Copies the @context. - - - A copied #GstParseContext - - - - - a #GstParseContext - - - - - - Frees a parse context previously allocated with gst_parse_context_new(). - - - - - - - a #GstParseContext - - - - - - Retrieve missing elements from a previous run of gst_parse_launch_full() -or gst_parse_launchv_full(). Will only return results if an error code -of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned. - - - a - %NULL-terminated array of element factory name strings of missing - elements. Free with g_strfreev() when no longer needed. - - - - - - - a #GstParseContext - - - - - - - The different parsing errors that can occur. - - A syntax error occurred. - - - The description contained an unknown element - - - An element did not have a specified property - - - There was an error linking two pads. - - - There was an error setting a property - - - An empty bin was specified. - - - An empty description was specified - - - A delayed link did not get resolved. - - - Get the error quark used by the parsing subsystem. - - the quark of the parse errors. - - - - - - Parsing options. - - Do not use any special parsing options. - - - Always return %NULL when an error occurs - (default behaviour is to return partially constructed bins or elements - in some cases) - - - If a bin only has a single element, - just return the element. - - - If more than one toplevel element is described - by the pipeline description string, put them in a #GstBin instead of a - #GstPipeline. (Since: 1.10) - - - - A #GstPipeline is a special #GstBin used as the toplevel container for -the filter graph. The #GstPipeline will manage the selection and -distribution of a global #GstClock as well as provide a #GstBus to the -application. - -gst_pipeline_new() is used to create a pipeline. when you are done with -the pipeline, use gst_object_unref() to free its resources including all -added #GstElement objects (if not otherwise referenced). - -Elements are added and removed from the pipeline using the #GstBin -methods like gst_bin_add() and gst_bin_remove() (see #GstBin). - -Before changing the state of the #GstPipeline (see #GstElement) a #GstBus -can be retrieved with gst_pipeline_get_bus(). This bus can then be -used to receive #GstMessage from the elements in the pipeline. - -By default, a #GstPipeline will automatically flush the pending #GstBus -messages when going to the NULL state to ensure that no circular -references exist when no messages are read from the #GstBus. This -behaviour can be changed with gst_pipeline_set_auto_flush_bus(). - -When the #GstPipeline performs the PAUSED to PLAYING state change it will -select a clock for the elements. The clock selection algorithm will by -default select a clock provided by an element that is most upstream -(closest to the source). For live pipelines (ones that return -#GST_STATE_CHANGE_NO_PREROLL from the gst_element_set_state() call) this -will select the clock provided by the live source. For normal pipelines -this will select a clock provided by the sinks (most likely the audio -sink). If no element provides a clock, a default #GstSystemClock is used. - -The clock selection can be controlled with the gst_pipeline_use_clock() -method, which will enforce a given clock on the pipeline. With -gst_pipeline_auto_clock() the default clock selection algorithm can be -restored. - -A #GstPipeline maintains a running time for the elements. The running -time is defined as the difference between the current clock time and -the base time. When the pipeline goes to READY or a flushing seek is -performed on it, the running time is reset to 0. When the pipeline is -set from PLAYING to PAUSED, the current clock time is sampled and used to -configure the base time for the elements when the pipeline is set -to PLAYING again. The effect is that the running time (as the difference -between the clock time and the base time) will count how much time was spent -in the PLAYING state. This default behaviour can be changed with the -gst_element_set_start_time() method. - - - - Create a new pipeline with the given name. - - - newly created GstPipeline - -MT safe. - - - - - name of new pipeline - - - - - - Let @pipeline select a clock automatically. This is the default -behaviour. - -Use this function if you previous forced a fixed clock with -gst_pipeline_use_clock() and want to restore the default -pipeline clock selection algorithm. - -MT safe. - - - - - - - a #GstPipeline - - - - - - Check if @pipeline will automatically flush messages when going to -the NULL state. - - - whether the pipeline will automatically flush its bus when -going from READY to NULL state or not. - -MT safe. - - - - - a #GstPipeline - - - - - - Gets the #GstBus of @pipeline. The bus allows applications to receive -#GstMessage packets. - - - a #GstBus, unref after usage. - -MT safe. - - - - - a #GstPipeline - - - - - - Gets the current clock used by @pipeline. Users of object -oriented languages should use gst_pipeline_get_pipeline_clock() -to avoid confusion with gst_element_get_clock() which has a different behavior. - -Unlike gst_element_get_clock(), this function will always return a -clock, even if the pipeline is not in the PLAYING state. - - - a #GstClock, unref after usage. - - - - - a #GstPipeline - - - - - - Get the configured delay (see gst_pipeline_set_delay()). - - - The configured delay. - -MT safe. - - - - - a #GstPipeline - - - - - - Gets the latency that should be configured on the pipeline. See -gst_pipeline_set_latency(). - - - Latency to configure on the pipeline or GST_CLOCK_TIME_NONE - - - - - a #GstPipeline - - - - - - Gets the current clock used by @pipeline. - -Unlike gst_element_get_clock(), this function will always return a -clock, even if the pipeline is not in the PLAYING state. - - - a #GstClock, unref after usage. - - - - - a #GstPipeline - - - - - - Usually, when a pipeline goes from READY to NULL state, it automatically -flushes all pending messages on the bus, which is done for refcounting -purposes, to break circular references. - -This means that applications that update state using (async) bus messages -(e.g. do certain things when a pipeline goes from PAUSED to READY) might -not get to see messages when the pipeline is shut down, because they might -be flushed before they can be dispatched in the main thread. This behaviour -can be disabled using this function. - -It is important that all messages on the bus are handled when the -automatic flushing is disabled else memory leaks will be introduced. - -MT safe. - - - - - - - a #GstPipeline - - - - whether or not to automatically flush the bus when -the pipeline goes from READY to NULL state - - - - - - Set the clock for @pipeline. The clock will be distributed -to all the elements managed by the pipeline. - - - %TRUE if the clock could be set on the pipeline. %FALSE if - some element did not accept the clock. - -MT safe. - - - - - a #GstPipeline - - - - the clock to set - - - - - - Set the expected delay needed for all elements to perform the -PAUSED to PLAYING state change. @delay will be added to the -base time of the elements so that they wait an additional @delay -amount of time before starting to process buffers and cannot be -#GST_CLOCK_TIME_NONE. - -This option is used for tuning purposes and should normally not be -used. - -MT safe. - - - - - - - a #GstPipeline - - - - the delay - - - - - - Sets the latency that should be configured on the pipeline. Setting -GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum -latency from the LATENCY query. Setting this is usually not required and -the pipeline will figure out an appropriate latency automatically. - -Setting a too low latency, especially lower than the minimum latency from -the LATENCY query, will most likely cause the pipeline to fail. - - - - - - - a #GstPipeline - - - - latency to configure - - - - - - Force @pipeline to use the given @clock. The pipeline will -always use the given clock even if new clock providers are added -to this pipeline. - -If @clock is %NULL all clocking will be disabled which will make -the pipeline run as fast as possible. - -MT safe. - - - - - - - a #GstPipeline - - - - the clock to use - - - - - - Whether or not to automatically flush all messages on the -pipeline's bus when going from READY to NULL state. Please see -gst_pipeline_set_auto_flush_bus() for more information on this option. - - - - The expected delay needed for elements to spin up to the -PLAYING state expressed in nanoseconds. -see gst_pipeline_set_delay() for more information on this option. - - - - Latency to configure on the pipeline. See gst_pipeline_set_latency(). - - - - - - - The fixed clock of the pipeline, used when - GST_PIPELINE_FLAG_FIXED_CLOCK is set. - - - - The stream time of the pipeline. A better name for this - property would be the running_time, the total time spent in the - PLAYING state without being flushed. (deprecated, use the start_time - on GstElement). - - - - Extra delay added to base_time to compensate for computing delays - when setting elements to PLAYING. - - - - - - - - - - - - - - - - - - - - - - - - Pipeline flags - - this pipeline works with a fixed clock - - - offset to define more flags - - - - - - - GStreamer is extensible, so #GstElement instances can be loaded at runtime. -A plugin system can provide one or more of the basic GStreamer -#GstPluginFeature subclasses. - -A plugin should export a symbol `gst_plugin_desc` that is a -struct of type #GstPluginDesc. -the plugin loader will check the version of the core library the plugin was -linked against and will create a new #GstPlugin. It will then call the -#GstPluginInitFunc function that was provided in the -`gst_plugin_desc`. - -Once you have a handle to a #GstPlugin (e.g. from the #GstRegistry), you -can add any object that subclasses #GstPluginFeature. - -Usually plugins are always automatically loaded so you don't need to call -gst_plugin_load() explicitly to bring it into memory. There are options to -statically link plugins to an app or even use GStreamer without a plugin -repository in which case gst_plugin_load() can be needed to bring the plugin -into memory. - - - Unrefs each member of @list, then frees the list. - - - - - - - list of #GstPlugin - - - - - - - - Load the named plugin. Refs the plugin. - - - a reference to a loaded plugin, or -%NULL on error. - - - - - name of plugin to load - - - - - - Loads the given plugin and refs it. Caller needs to unref after use. - - - a reference to the existing loaded GstPlugin, a -reference to the newly-loaded GstPlugin, or %NULL if an error occurred. - - - - - the plugin filename to load - - - - - - Registers a static plugin, ie. a plugin which is private to an application -or library and contained within the application or library (as opposed to -being shipped as a separate module file). - -You must make sure that GStreamer has been initialised (with gst_init() or -via gst_init_get_option_group()) before calling this function. - - - %TRUE if the plugin was registered correctly, otherwise %FALSE. - - - - - the major version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MAJOR here - - - - the minor version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MINOR here - - - - a unique name of the plugin (ideally prefixed with an application- or - library-specific namespace prefix in order to avoid name conflicts in - case a similar plugin with the same name ever gets added to GStreamer) - - - - description of the plugin - - - - pointer to the init function of this plugin. - - - - version string of the plugin - - - - effective license of plugin. Must be one of the approved licenses - (see #GstPluginDesc above) or the plugin will not be registered. - - - - source module plugin belongs to - - - - shipped package plugin belongs to - - - - URL to provider of plugin - - - - - - Registers a static plugin, ie. a plugin which is private to an application -or library and contained within the application or library (as opposed to -being shipped as a separate module file) with a #GstPluginInitFullFunc -which allows user data to be passed to the callback function (useful -for bindings). - -You must make sure that GStreamer has been initialised (with gst_init() or -via gst_init_get_option_group()) before calling this function. - - - %TRUE if the plugin was registered correctly, otherwise %FALSE. - - - - - the major version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MAJOR here - - - - the minor version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MINOR here - - - - a unique name of the plugin (ideally prefixed with an application- or - library-specific namespace prefix in order to avoid name conflicts in - case a similar plugin with the same name ever gets added to GStreamer) - - - - description of the plugin - - - - pointer to the init function with user data - of this plugin. - - - - version string of the plugin - - - - effective license of plugin. Must be one of the approved licenses - (see #GstPluginDesc above) or the plugin will not be registered. - - - - source module plugin belongs to - - - - shipped package plugin belongs to - - - - URL to provider of plugin - - - - gpointer to user data - - - - - - Make GStreamer aware of external dependencies which affect the feature -set of this plugin (ie. the elements or typefinders associated with it). - -GStreamer will re-inspect plugins with external dependencies whenever any -of the external dependencies change. This is useful for plugins which wrap -other plugin systems, e.g. a plugin which wraps a plugin-based visualisation -library and makes visualisations available as GStreamer elements, or a -codec loader which exposes elements and/or caps dependent on what external -codec libraries are currently installed. - - - - - - - a #GstPlugin - - - - %NULL-terminated array of environment variables affecting the - feature set of the plugin (e.g. an environment variable containing - paths where to look for additional modules/plugins of a library), - or %NULL. Environment variable names may be followed by a path component - which will be added to the content of the environment variable, e.g. - "HOME/.mystuff/plugins". - - - - - - %NULL-terminated array of directories/paths where dependent files - may be, or %NULL. - - - - - - %NULL-terminated array of file names (or file name suffixes, - depending on @flags) to be used in combination with the paths from - @paths and/or the paths extracted from the environment variables in - @env_vars, or %NULL. - - - - - - optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE - - - - - - Make GStreamer aware of external dependencies which affect the feature -set of this plugin (ie. the elements or typefinders associated with it). - -GStreamer will re-inspect plugins with external dependencies whenever any -of the external dependencies change. This is useful for plugins which wrap -other plugin systems, e.g. a plugin which wraps a plugin-based visualisation -library and makes visualisations available as GStreamer elements, or a -codec loader which exposes elements and/or caps dependent on what external -codec libraries are currently installed. - -Convenience wrapper function for gst_plugin_add_dependency() which -takes simple strings as arguments instead of string arrays, with multiple -arguments separated by predefined delimiters (see above). - - - - - - - the #GstPlugin - - - - one or more environment variables (separated by ':', ';' or ','), - or %NULL. Environment variable names may be followed by a path component - which will be added to the content of the environment variable, e.g. - "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH" - - - - one ore more directory paths (separated by ':' or ';' or ','), - or %NULL. Example: "/usr/lib/mystuff/plugins" - - - - one or more file names or file name suffixes (separated by commas), - or %NULL - - - - optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE - - - - - - Gets the plugin specific data cache. If it is %NULL there is no cached data -stored. This is the case when the registry is getting rebuilt. - - - The cached data as a -#GstStructure or %NULL. - - - - - a plugin - - - - - - Get the long descriptive name of the plugin - - - the long name of the plugin - - - - - plugin to get long name of - - - - - - get the filename of the plugin - - - the filename of the plugin - - - - - plugin to get the filename of - - - - - - get the license of the plugin - - - the license of the plugin - - - - - plugin to get the license of - - - - - - Get the short name of the plugin - - - the name of the plugin - - - - - plugin to get the name of - - - - - - get the URL where the plugin comes from - - - the origin of the plugin - - - - - plugin to get the origin of - - - - - - get the package the plugin belongs to. - - - the package of the plugin - - - - - plugin to get the package of - - - - - - Get the release date (and possibly time) in form of a string, if available. - -For normal GStreamer plugin releases this will usually just be a date in -the form of "YYYY-MM-DD", while pre-releases and builds from git may contain -a time component after the date as well, in which case the string will be -formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z"). - -There may be plugins that do not have a valid release date set on them. - - - the date string of the plugin, or %NULL if not -available. - - - - - plugin to get the release date of - - - - - - get the source module the plugin belongs to. - - - the source of the plugin - - - - - plugin to get the source of - - - - - - get the version of the plugin - - - the version of the plugin - - - - - plugin to get the version of - - - - - - queries if the plugin is loaded into memory - - - %TRUE is loaded, %FALSE otherwise - - - - - plugin to query - - - - - - Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is -untouched. The normal use pattern of this function goes like this: - -|[ -GstPlugin *loaded_plugin; -loaded_plugin = gst_plugin_load (plugin); -// presumably, we're no longer interested in the potentially-unloaded plugin -gst_object_unref (plugin); -plugin = loaded_plugin; -]| - - - a reference to a loaded plugin, or -%NULL on error. - - - - - plugin to load - - - - - - Adds plugin specific data to cache. Passes the ownership of the structure to -the @plugin. - -The cache is flushed every time the registry is rebuilt. - - - - - - - a plugin - - - - a structure containing the data to cache - - - - - - - - Ignore enum members when generating - the plugins cache. This is useful if the members of the enum are generated - dynamically, in order not to expose incorrect documentation to the end user. - - - - - - - Flags used in connection with gst_plugin_add_dependency(). - - no special flags - - - recurse into subdirectories - - - use paths - argument only if none of the environment variables is set - - - interpret - filename argument as filter suffix and check all matching files in - the directory - - - interpret - filename argument as filter prefix and check all matching files in - the directory. Since: 1.8. - - - interpret - non-absolute paths as relative to the main executable directory. Since - 1.14. - - - - A plugin should export a variable of this type called plugin_desc. The plugin -loader will use the data provided there to initialize the plugin. - -The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL, -BSD, MIT/X11, Proprietary, unknown. - - - the major version number of core that plugin was compiled for - - - - the minor version number of core that plugin was compiled for - - - - a unique name of the plugin - - - - description of plugin - - - - pointer to the init function of this plugin. - - - - version of the plugin - - - - effective license of plugin - - - - source module plugin belongs to - - - - shipped package plugin belongs to - - - - URL to provider of plugin - - - - date time string in ISO 8601 - format (or rather, a subset thereof), or %NULL. Allowed are the - following formats: "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with - 'T' a separator and 'Z' indicating UTC/Zulu time). This field - should be set via the GST_PACKAGE_RELEASE_DATETIME - preprocessor macro. - - - - - - - - - - The plugin loading errors - - The plugin could not be loaded - - - The plugin has unresolved dependencies - - - The plugin has already be loaded from a different file - - - Get the error quark. - - The error quark used in GError messages - - - - - - This is a base class for anything that can be added to a #GstPlugin. - - - Copies the list of features. Caller should call @gst_plugin_feature_list_free -when done with the list. - - - a copy of @list, - with each feature's reference count incremented. - - - - - - - list - of #GstPluginFeature - - - - - - - - Debug the plugin feature names in @list. - - - - - - - a #GList of - plugin features - - - - - - - - Unrefs each member of @list, then frees the list. - - - - - - - list - of #GstPluginFeature - - - - - - - - Compares the two given #GstPluginFeature instances. This function can be -used as a #GCompareFunc when sorting by rank and then by name. - - - negative value if the rank of p1 > the rank of p2 or the ranks are -equal but the name of p1 comes before the name of p2; zero if the rank -and names are equal; positive value if the rank of p1 < the rank of p2 or the -ranks are equal but the name of p2 comes before the name of p1 - - - - - a #GstPluginFeature - - - - a #GstPluginFeature - - - - - - Checks whether the given plugin feature is at least - the required version - - - %TRUE if the plugin feature has at least - the required version, otherwise %FALSE. - - - - - a feature - - - - minimum required major version - - - - minimum required minor version - - - - minimum required micro version - - - - - - Get the plugin that provides this feature. - - - the plugin that provides this - feature, or %NULL. Unref with gst_object_unref() when no - longer needed. - - - - - a feature - - - - - - Get the name of the plugin that provides this feature. - - - the name of the plugin that provides this - feature, or %NULL if the feature is not associated with a - plugin. - - - - - a feature - - - - - - Gets the rank of a plugin feature. - - - The rank of the feature - - - - - a feature - - - - - - Loads the plugin containing @feature if it's not already loaded. @feature is -unaffected; use the return value instead. - -Normally this function is used like this: -|[<!-- language="C" --> -GstPluginFeature *loaded_feature; - -loaded_feature = gst_plugin_feature_load (feature); -// presumably, we're no longer interested in the potentially-unloaded feature -gst_object_unref (feature); -feature = loaded_feature; -]| - - - a reference to the loaded -feature, or %NULL on error - - - - - the plugin feature to check - - - - - - Specifies a rank for a plugin feature, so that autoplugging uses -the most appropriate feature. - - - - - - - feature to rank - - - - rank value - higher number means more priority rank - - - - - - - - - - A function that can be used with e.g. gst_registry_feature_filter() -to get a list of pluginfeature that match certain criteria. - - - %TRUE for a positive match, %FALSE otherwise - - - - - the pluginfeature to check - - - - the user_data that has been passed on e.g. - gst_registry_feature_filter() - - - - - - A function that can be used with e.g. gst_registry_plugin_filter() -to get a list of plugins that match certain criteria. - - - %TRUE for a positive match, %FALSE otherwise - - - - - the plugin to check - - - - the user_data that has been passed on e.g. gst_registry_plugin_filter() - - - - - - The plugin loading state - - Temporarily loaded plugins - - - The plugin won't be scanned (again) - - - - A plugin should provide a pointer to a function of either #GstPluginInitFunc -or this type in the plugin_desc struct. -The function will be called by the loader at startup. One would then -register each #GstPluginFeature. This version allows -user data to be passed to init function (useful for bindings). - - - %TRUE if plugin initialised successfully - - - - - The plugin object - - - - extra data - - - - - - A plugin should provide a pointer to a function of this type in the -plugin_desc struct. -This function will be called by the loader at startup. One would then -register each #GstPluginFeature. - - - %TRUE if plugin initialised successfully - - - - - The plugin object - - - - - - A #GstPoll keeps track of file descriptors much like fd_set (used with -select ()) or a struct pollfd array (used with poll ()). Once created with -gst_poll_new(), the set can be used to wait for file descriptors to be -readable and/or writable. It is possible to make this wait be controlled -by specifying %TRUE for the @controllable flag when creating the set (or -later calling gst_poll_set_controllable()). - -New file descriptors are added to the set using gst_poll_add_fd(), and -removed using gst_poll_remove_fd(). Controlling which file descriptors -should be waited for to become readable and/or writable are done using -gst_poll_fd_ctl_read(), gst_poll_fd_ctl_write() and gst_poll_fd_ctl_pri(). - -Use gst_poll_wait() to wait for the file descriptors to actually become -readable and/or writable, or to timeout if no file descriptor is available -in time. The wait can be controlled by calling gst_poll_restart() and -gst_poll_set_flushing(). - -Once the file descriptor set has been waited for, one can use -gst_poll_fd_has_closed() to see if the file descriptor has been closed, -gst_poll_fd_has_error() to see if it has generated an error, -gst_poll_fd_can_read() to see if it is possible to read from the file -descriptor, and gst_poll_fd_can_write() to see if it is possible to -write to it. - - - Add a file descriptor to the file descriptor set. - - - %TRUE if the file descriptor was successfully added to the set. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Check if @fd in @set has data to be read. - - - %TRUE if the descriptor has data to be read. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Check if @fd in @set can be used for writing. - - - %TRUE if the descriptor can be used for writing. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Control whether the descriptor @fd in @set will be monitored for -exceptional conditions (POLLPRI). - -Not implemented on Windows (will just return %FALSE there). - - - %TRUE if the descriptor was successfully updated. - - - - - a file descriptor set. - - - - a file descriptor. - - - - a new status. - - - - - - Control whether the descriptor @fd in @set will be monitored for -readability. - - - %TRUE if the descriptor was successfully updated. - - - - - a file descriptor set. - - - - a file descriptor. - - - - a new status. - - - - - - Control whether the descriptor @fd in @set will be monitored for -writability. - - - %TRUE if the descriptor was successfully updated. - - - - - a file descriptor set. - - - - a file descriptor. - - - - a new status. - - - - - - Check if @fd in @set has closed the connection. - - - %TRUE if the connection was closed. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Check if @fd in @set has an error. - - - %TRUE if the descriptor has an error. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Check if @fd in @set has an exceptional condition (POLLPRI). - -Not implemented on Windows (will just return %FALSE there). - - - %TRUE if the descriptor has an exceptional condition. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Mark @fd as ignored so that the next call to gst_poll_wait() will yield -the same result for @fd as last time. This function must be called if no -operation (read/write/recv/send/etc.) will be performed on @fd before -the next call to gst_poll_wait(). - -The reason why this is needed is because the underlying implementation -might not allow querying the fd more than once between calls to one of -the re-enabling operations. - - - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Free a file descriptor set. - - - - - - - a file descriptor set. - - - - - - Get a GPollFD for the reading part of the control socket. This is useful when -integrating with a GSource and GMainLoop. - - - - - - - a #GstPoll - - - - a #GPollFD - - - - - - Read a byte from the control socket of the controllable @set. - -This function only works for timer #GstPoll objects created with -gst_poll_new_timer(). - - - %TRUE on success. %FALSE when when there was no byte to read or -reading the byte failed. If there was no byte to read, and only then, errno -will contain EWOULDBLOCK or EAGAIN. For all other values of errno this always signals a -critical error. - - - - - a #GstPoll. - - - - - - Remove a file descriptor from the file descriptor set. - - - %TRUE if the file descriptor was successfully removed from the set. - - - - - a file descriptor set. - - - - a file descriptor. - - - - - - Restart any gst_poll_wait() that is in progress. This function is typically -used after adding or removing descriptors to @set. - -If @set is not controllable, then this call will have no effect. - -This function only works for non-timer #GstPoll objects created with -gst_poll_new(). - - - - - - - a #GstPoll. - - - - - - When @controllable is %TRUE, this function ensures that future calls to -gst_poll_wait() will be affected by gst_poll_restart() and -gst_poll_set_flushing(). - -This function only works for non-timer #GstPoll objects created with -gst_poll_new(). - - - %TRUE if the controllability of @set could be updated. - - - - - a #GstPoll. - - - - new controllable state. - - - - - - When @flushing is %TRUE, this function ensures that current and future calls -to gst_poll_wait() will return -1, with errno set to EBUSY. - -Unsetting the flushing state will restore normal operation of @set. - -This function only works for non-timer #GstPoll objects created with -gst_poll_new(). - - - - - - - a #GstPoll. - - - - new flushing state. - - - - - - Wait for activity on the file descriptors in @set. This function waits up to -the specified @timeout. A timeout of #GST_CLOCK_TIME_NONE waits forever. - -For #GstPoll objects created with gst_poll_new(), this function can only be -called from a single thread at a time. If called from multiple threads, --1 will be returned with errno set to EPERM. - -This is not true for timer #GstPoll objects created with -gst_poll_new_timer(), where it is allowed to have multiple threads waiting -simultaneously. - - - The number of #GstPollFD in @set that have activity or 0 when no -activity was detected after @timeout. If an error occurs, -1 is returned -and errno is set. - - - - - a #GstPoll. - - - - a timeout in nanoseconds. - - - - - - Write a byte to the control socket of the controllable @set. -This function is mostly useful for timer #GstPoll objects created with -gst_poll_new_timer(). - -It will make any current and future gst_poll_wait() function return with -1, meaning the control socket is set. After an equal amount of calls to -gst_poll_read_control() have been performed, calls to gst_poll_wait() will -block again until their timeout expired. - -This function only works for timer #GstPoll objects created with -gst_poll_new_timer(). - - - %TRUE on success. %FALSE when when the byte could not be written. -errno contains the detailed error code but will never be EAGAIN, EINTR or -EWOULDBLOCK. %FALSE always signals a critical error. - - - - - a #GstPoll. - - - - - - Create a new file descriptor set. If @controllable, it -is possible to restart or flush a call to gst_poll_wait() with -gst_poll_restart() and gst_poll_set_flushing() respectively. - -Free-function: gst_poll_free - - - a new #GstPoll, or %NULL in - case of an error. Free with gst_poll_free(). - - - - - whether it should be possible to control a wait. - - - - - - Create a new poll object that can be used for scheduling cancellable -timeouts. - -A timeout is performed with gst_poll_wait(). Multiple timeouts can be -performed from different threads. - -Free-function: gst_poll_free - - - a new #GstPoll, or %NULL in - case of an error. Free with gst_poll_free(). - - - - - - A file descriptor object. - - - a file descriptor - - - - - - - Initializes @fd. Alternatively you can initialize it with -#GST_POLL_FD_INIT. - - - - - - - a #GstPollFD - - - - - - - This interface offers methods to query and manipulate parameter preset sets. -A preset is a bunch of property settings, together with meta data and a name. -The name of a preset serves as key for subsequent method calls to manipulate -single presets. -All instances of one type will share the list of presets. The list is created -on demand, if presets are not used, the list is not created. - -The interface comes with a default implementation that serves most plugins. -Wrapper plugins will override most methods to implement support for the -native preset format of those wrapped plugins. -One method that is useful to be overridden is gst_preset_get_property_names(). -With that one can control which properties are saved and in which order. -When implementing support for read-only presets, one should set the vmethods -for gst_preset_save_preset() and gst_preset_delete_preset() to %NULL. -Applications can use gst_preset_is_editable() to check for that. - -The default implementation supports presets located in a system directory, -application specific directory and in the users home directory. When getting -a list of presets individual presets are read and overlaid in 1) system, -2) application and 3) user order. Whenever an earlier entry is newer, the -later entries will be updated. Since 1.8 you can also provide extra paths -where to find presets through the GST_PRESET_PATH environment variable. -Presets found in those paths will be considered as "app presets". - - - Gets the directory for application specific presets if set by the -application. - - - the directory or %NULL, don't free or modify -the string - - - - - Sets an extra directory as an absolute path that should be considered when -looking for presets. Any presets in the application dir will shadow the -system presets. - - - %TRUE for success, %FALSE if the dir already has been set - - - - - the application specific preset dir - - - - - - Delete the given preset. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to remove - - - - - - Gets the @value for an existing meta data @tag. Meta data @tag names can be -something like e.g. "comment". Returned values need to be released when done. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name -or no value for the given @tag - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - value - - - - - - Get a copy of preset names as a %NULL terminated string array. - - - - list with names, use g_strfreev() after usage. - - - - - - - a #GObject that implements #GstPreset - - - - - - Get a the names of the GObject properties that can be used for presets. - - - an - array of property names which should be freed with g_strfreev() after use. - - - - - - - a #GObject that implements #GstPreset - - - - - - Load the given preset. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to load - - - - - - Renames a preset. If there is already a preset by the @new_name it will be -overwritten. - - - %TRUE for success, %FALSE if e.g. there is no preset with @old_name - - - - - a #GObject that implements #GstPreset - - - - current preset name - - - - new preset name - - - - - - Save the current object settings as a preset under the given name. If there -is already a preset by this @name it will be overwritten. - - - %TRUE for success, %FALSE - - - - - a #GObject that implements #GstPreset - - - - preset name to save - - - - - - Sets a new @value for an existing meta data item or adds a new item. Meta -data @tag names can be something like e.g. "comment". Supplying %NULL for the -@value will unset an existing value. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - new value - - - - - - Delete the given preset. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to remove - - - - - - Gets the @value for an existing meta data @tag. Meta data @tag names can be -something like e.g. "comment". Returned values need to be released when done. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name -or no value for the given @tag - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - value - - - - - - Get a copy of preset names as a %NULL terminated string array. - - - - list with names, use g_strfreev() after usage. - - - - - - - a #GObject that implements #GstPreset - - - - - - Get a the names of the GObject properties that can be used for presets. - - - an - array of property names which should be freed with g_strfreev() after use. - - - - - - - a #GObject that implements #GstPreset - - - - - - Check if one can add new presets, change existing ones and remove presets. - - - %TRUE if presets are editable or %FALSE if they are static - - - - - a #GObject that implements #GstPreset - - - - - - Load the given preset. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to load - - - - - - Renames a preset. If there is already a preset by the @new_name it will be -overwritten. - - - %TRUE for success, %FALSE if e.g. there is no preset with @old_name - - - - - a #GObject that implements #GstPreset - - - - current preset name - - - - new preset name - - - - - - Save the current object settings as a preset under the given name. If there -is already a preset by this @name it will be overwritten. - - - %TRUE for success, %FALSE - - - - - a #GObject that implements #GstPreset - - - - preset name to save - - - - - - Sets a new @value for an existing meta data item or adds a new item. Meta -data @tag names can be something like e.g. "comment". Supplying %NULL for the -@value will unset an existing value. - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - new value - - - - - - - #GstPreset interface. - - - parent interface type. - - - - - - - - list with names, use g_strfreev() after usage. - - - - - - - a #GObject that implements #GstPreset - - - - - - - - - - an - array of property names which should be freed with g_strfreev() after use. - - - - - - - a #GObject that implements #GstPreset - - - - - - - - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to load - - - - - - - - - - %TRUE for success, %FALSE - - - - - a #GObject that implements #GstPreset - - - - preset name to save - - - - - - - - - - %TRUE for success, %FALSE if e.g. there is no preset with @old_name - - - - - a #GObject that implements #GstPreset - - - - current preset name - - - - new preset name - - - - - - - - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name to remove - - - - - - - - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - new value - - - - - - - - - - %TRUE for success, %FALSE if e.g. there is no preset with that @name -or no value for the given @tag - - - - - a #GObject that implements #GstPreset - - - - preset name - - - - meta data item name - - - - value - - - - - - - - - - - - - The type of a %GST_MESSAGE_PROGRESS. The progress messages inform the -application of the status of asynchronous tasks. - - A new task started. - - - A task completed and a new one continues. - - - A task completed. - - - A task was canceled. - - - A task caused an error. An error message is also - posted on the bus. - - - - The #GstPromise object implements the container for values that may -be available later. i.e. a Future or a Promise in -<https://en.wikipedia.org/wiki/Futures_and_promises>. -As with all Future/Promise-like functionality, there is the concept of the -producer of the value and the consumer of the value. - -A #GstPromise is created with gst_promise_new() by the consumer and passed -to the producer to avoid thread safety issues with the change callback. -A #GstPromise can be replied to with a value (or an error) by the producer -with gst_promise_reply(). The exact value returned is defined by the API -contract of the producer and %NULL may be a valid reply. -gst_promise_interrupt() is for the consumer to -indicate to the producer that the value is not needed anymore and producing -that value can stop. The @GST_PROMISE_RESULT_EXPIRED state set by a call -to gst_promise_expire() indicates to the consumer that a value will never -be produced and is intended to be called by a third party that implements -some notion of message handling such as #GstBus. -A callback can also be installed at #GstPromise creation for -result changes with gst_promise_new_with_change_func(). -The change callback can be used to chain #GstPromises's together as in the -following example. -|[<!-- language="C" --> -const GstStructure *reply; -GstPromise *p; -if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) - return; // interrupted or expired value -reply = gst_promise_get_reply (promise); -if (error in reply) - return; // propagate error -p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); -pass p to promise-using API -]| - -Each #GstPromise starts out with a #GstPromiseResult of -%GST_PROMISE_RESULT_PENDING and only ever transitions once -into one of the other #GstPromiseResult's. - -In order to support multi-threaded code, gst_promise_reply(), -gst_promise_interrupt() and gst_promise_expire() may all be from -different threads with some restrictions and the final result of the promise -is whichever call is made first. There are two restrictions on ordering: - -1. That gst_promise_reply() and gst_promise_interrupt() cannot be called -after gst_promise_expire() -2. That gst_promise_reply() and gst_promise_interrupt() -cannot be called twice. - -The change function set with gst_promise_new_with_change_func() is -called directly from either the gst_promise_reply(), -gst_promise_interrupt() or gst_promise_expire() and can be called -from an arbitrary thread. #GstPromise using APIs can restrict this to -a single thread or a subset of threads but that is entirely up to the API -that uses #GstPromise. - - - parent #GstMiniObject - - - - - - a new #GstPromise - - - - - @func will be called exactly once when transitioning out of -%GST_PROMISE_RESULT_PENDING into any of the other #GstPromiseResult -states. - - - a new #GstPromise - - - - - a #GstPromiseChangeFunc to call - - - - argument to call @func with - - - - notification function that @user_data is no longer needed - - - - - - Expire a @promise. This will wake up any waiters with -%GST_PROMISE_RESULT_EXPIRED. Called by a message loop when the parent -message is handled and/or destroyed (possibly unanswered). - - - - - - - a #GstPromise - - - - - - Retrieve the reply set on @promise. @promise must be in -%GST_PROMISE_RESULT_REPLIED and the returned structure is owned by @promise - - - The reply set on @promise - - - - - a #GstPromise - - - - - - Interrupt waiting for a @promise. This will wake up any waiters with -%GST_PROMISE_RESULT_INTERRUPTED. Called when the consumer does not want -the value produced anymore. - - - - - - - a #GstPromise - - - - - - Set a reply on @promise. This will wake up any waiters with -%GST_PROMISE_RESULT_REPLIED. Called by the producer of the value to -indicate success (or failure). - -If @promise has already been interrupted by the consumer, then this reply -is not visible to the consumer. - - - - - - - a #GstPromise - - - - a #GstStructure with the the reply contents - - - - - - Wait for @promise to move out of the %GST_PROMISE_RESULT_PENDING state. -If @promise is not in %GST_PROMISE_RESULT_PENDING then it will return -immediately with the current result. - - - the result of the promise - - - - - a #GstPromise - - - - - - - - - - - - - a #GstPromise - - - - user data - - - - - - The result of a #GstPromise - - Initial state. Waiting for transition to any - other state. - - - Interrupted by the consumer as it doesn't - want the value anymore. - - - A producer marked a reply - - - The promise expired (the carrying object - lost all refs) and the promise will never be fulfilled. - - - - Metadata type that holds information about a sample from a protection-protected -track, including the information needed to decrypt it (if it is encrypted). - - - the parent #GstMeta. - - - - the cryptographic information needed to decrypt the sample. - - - - - - - - - - - - - Invoke the default chain function of the proxy pad. - - - a #GstFlowReturn from the pad. - - - - - a sink #GstPad, returns GST_FLOW_ERROR if not. - - - - the parent of @pad or %NULL - - - - the #GstBuffer to send, return GST_FLOW_ERROR - if not. - - - - - - Invoke the default chain list function of the proxy pad. - - - a #GstFlowReturn from the pad. - - - - - a sink #GstPad, returns GST_FLOW_ERROR if not. - - - - the parent of @pad or %NULL - - - - the #GstBufferList to send, return GST_FLOW_ERROR - if not. - - - - - - Invoke the default getrange function of the proxy pad. - - - a #GstFlowReturn from the pad. - - - - - a src #GstPad, returns #GST_FLOW_ERROR if not. - - - - the parent of @pad - - - - The start offset of the buffer - - - - The length of the buffer - - - - a pointer to hold the #GstBuffer, - returns #GST_FLOW_ERROR if %NULL. - - - - - - Invoke the default iterate internal links function of the proxy pad. - - - a #GstIterator of #GstPad, or %NULL if @pad -has no parent. Unref each returned pad with gst_object_unref(). - - - - - the #GstPad to get the internal links of. - - - - the parent of @pad or %NULL - - - - - - Get the internal pad of @pad. Unref target pad after usage. - -The internal pad of a #GstGhostPad is the internally used -pad of opposite direction, which is used to link to the target. - - - the target #GstProxyPad, can -be %NULL. Unref target pad after usage. - - - - - the #GstProxyPad - - - - - - - - - - - - - - - - - - - - - - - - - - - The different types of QoS events that can be given to the -gst_event_new_qos() method. - - The QoS event type that is produced when upstream - elements are producing data too quickly and the element can't keep up - processing the data. Upstream should reduce their production rate. This - type is also used when buffers arrive early or in time. - - - The QoS event type that is produced when upstream - elements are producing data too slowly and need to speed up their - production rate. - - - The QoS event type that is produced when the - application enabled throttling to limit the data rate. - - - - - - - - - - - - - - - - - - Check if an query can travel downstream. - - - - the query to query - - - - - Check if an query is serialized with the data stream. - - - - the query to query - - - - - Check if an query can travel upstream. - - - - the query to query - - - - - when making custom query types, use this macro with the num and -the given flags - - - - the query number to create - - - the query flags - - - - - - - - - Get the #GstQueryType of the query. - - - - the query to query - - - - - The same thing as #GST_QUERY_TYPE_UPSTREAM | #GST_QUERY_TYPE_DOWNSTREAM. - - - - - Get a constant string representation of the #GstQueryType of the query. - - - - the query to query - - - - - Queries can be performed on pads (gst_pad_query()) and elements -(gst_element_query()). Please note that some queries might need a running -pipeline to work. - -Queries can be created using the gst_query_new_*() functions. -Query values can be set using gst_query_set_*(), and parsed using -gst_query_parse_*() helpers. - -The following example shows how to query the duration of a pipeline: -|[<!-- language="C" --> - GstQuery *query; - gboolean res; - query = gst_query_new_duration (GST_FORMAT_TIME); - res = gst_element_query (pipeline, query); - if (res) { - gint64 duration; - gst_query_parse_duration (query, NULL, &amp;duration); - g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); - } else { - g_print ("duration query failed..."); - } - gst_query_unref (query); -]| - - - The parent #GstMiniObject type - - - - the #GstQueryType - - - - Constructs a new query object for querying if @caps are accepted. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - a fixed #GstCaps - - - - - - Constructs a new query object for querying the allocation properties. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the negotiated caps - - - - return a pool - - - - - - Constructs a new query object for querying the bitrate. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Constructs a new query object for querying the buffering status of -a stream. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the default #GstFormat for the new query - - - - - - Constructs a new query object for querying the caps. - -The CAPS query should return the allowable caps for a pad in the context -of the element's state, its link to other elements, and the devices or files -it has opened. These caps must be a subset of the pad template caps. In the -NULL state with no links, the CAPS query should ideally return the same caps -as the pad template. In rare circumstances, an object property can affect -the caps returned by the CAPS query, but this is discouraged. - -For most filters, the caps returned by CAPS query is directly affected by the -allowed caps on other pads. For demuxers and decoders, the caps returned by -the srcpad's getcaps function is directly related to the stream data. Again, -the CAPS query should return the most specific caps it reasonably can, since this -helps with autoplugging. - -The @filter is used to restrict the result caps, only the caps matching -@filter should be returned from the CAPS query. Specifying a filter might -greatly reduce the amount of processing an element needs to do. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - a filter - - - - - - Constructs a new query object for querying the pipeline-local context. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Context type to query - - - - - - Constructs a new convert query object. Use gst_query_unref() -when done with it. A convert query is used to ask for a conversion between -one format and another. - -Free-function: gst_query_unref() - - - a #GstQuery - - - - - the source #GstFormat for the new query - - - - the value to convert - - - - the target #GstFormat - - - - - - Constructs a new custom query object. Use gst_query_unref() -when done with it. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the query type - - - - a structure for the query - - - - - - Constructs a new query object for querying the drain state. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Constructs a new stream duration query object to query in the given format. -Use gst_query_unref() when done with it. A duration query will give the -total length of the stream. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the #GstFormat for this duration query - - - - - - Constructs a new query object for querying formats of -the stream. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Constructs a new latency query object. -Use gst_query_unref() when done with it. A latency query is usually performed -by sinks to compensate for additional latency introduced by elements in the -pipeline. - -Free-function: gst_query_unref() - - - a #GstQuery - - - - - Constructs a new query stream position query object. Use gst_query_unref() -when done with it. A position query is used to query the current position -of playback in the streams, in some format. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the default #GstFormat for the new query - - - - - - Constructs a new query object for querying the scheduling properties. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Constructs a new query object for querying seeking properties of -the stream. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the default #GstFormat for the new query - - - - - - Constructs a new segment query object. Use gst_query_unref() -when done with it. A segment query is used to discover information about the -currently configured segment for playback. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - the #GstFormat for the new query - - - - - - Constructs a new query URI query object. Use gst_query_unref() -when done with it. An URI query is used to query the current URI -that is used by the source or sink. - -Free-function: gst_query_unref() - - - a new #GstQuery - - - - - Add @api with @params as one of the supported metadata API to @query. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - the metadata API - - - - API specific parameters - - - - - - Add @allocator and its @params as a supported memory allocator. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - the memory allocator - - - - a #GstAllocationParams - - - - - - Set the pool parameters in @query. - - - - - - - A valid #GstQuery of type GST_QUERY_ALLOCATION. - - - - the #GstBufferPool - - - - the buffer size - - - - the min buffers - - - - the max buffers - - - - - - Set the buffering-ranges array field in @query. The current last -start position of the array should be inferior to @start. - - - a #gboolean indicating if the range was added or not. - - - - - a GST_QUERY_BUFFERING type query #GstQuery - - - - start position of the range - - - - stop position of the range - - - - - - Add @mode as one of the supported scheduling modes to @query. - - - - - - - a GST_QUERY_SCHEDULING type query #GstQuery - - - - a #GstPadMode - - - - - - Copies the given query using the copy function of the parent #GstStructure. - -Free-function: gst_query_unref - - - a new copy of @q. - - - - - a #GstQuery to copy. - - - - - - Check if @query has metadata @api set. When this function returns %TRUE, -@index will contain the index where the requested API and the parameters -can be found. - - - %TRUE when @api is in the list of metadata. - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - the metadata API - - - - the index - - - - - - Retrieve the number of values currently stored in the -meta API array of the query's structure. - - - the metadata API array size as a #guint. - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - - - Retrieve the number of values currently stored in the -allocator params array of the query's structure. - -If no memory allocator is specified, the downstream element can handle -the default memory allocator. The first memory allocator in the query -should be generic and allow mapping to system memory, all following -allocators should be ordered by preference with the preferred one first. - - - the allocator array size as a #guint. - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - - - Retrieve the number of values currently stored in the -pool array of the query's structure. - - - the pool array size as a #guint. - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - - - Retrieve the number of values currently stored in the -buffered-ranges array of the query's structure. - - - the range array size as a #guint. - - - - - a GST_QUERY_BUFFERING type query #GstQuery - - - - - - Retrieve the number of values currently stored in the -scheduling mode array of the query's structure. - - - the scheduling mode array size as a #guint. - - - - - a GST_QUERY_SCHEDULING type query #GstQuery - - - - - - Get the structure of a query. - - - the #GstStructure of the query. The - structure is still owned by the query and will therefore be freed when the - query is unreffed. - - - - - a #GstQuery - - - - - - Check if @query has scheduling mode set. - -> When checking if upstream supports pull mode, it is usually not -> enough to just check for GST_PAD_MODE_PULL with this function, you -> also want to check whether the scheduling flags returned by -> gst_query_parse_scheduling() have the seeking flag set (meaning -> random access is supported, not only sequential pulls). - - - %TRUE when @mode is in the list of scheduling modes. - - - - - a GST_QUERY_SCHEDULING type query #GstQuery - - - - the scheduling mode - - - - - - Check if @query has scheduling mode set and @flags is set in -query scheduling flags. - - - %TRUE when @mode is in the list of scheduling modes - and @flags are compatible with query flags. - - - - - a GST_QUERY_SCHEDULING type query #GstQuery - - - - the scheduling mode - - - - #GstSchedulingFlags - - - - - - Get the caps from @query. The caps remains valid as long as @query remains -valid. - - - - - - - The query to parse - - - - A pointer to the caps - - - - - - Parse the result from @query and store in @result. - - - - - - - a GST_QUERY_ACCEPT_CAPS type query #GstQuery - - - - location for the result - - - - - - Parse an allocation query, writing the requested caps in @caps and -whether a pool is needed in @need_pool, if the respective parameters -are non-%NULL. - -Pool details can be retrieved using gst_query_get_n_allocation_pools() and -gst_query_parse_nth_allocation_pool(). - - - - - - - a #GstQuery - - - - The #GstCaps - - - - Whether a #GstBufferPool is needed - - - - - - Get the results of a bitrate query. See also gst_query_set_bitrate(). - - - - - - - a GST_QUERY_BITRATE type #GstQuery - - - - The resulting bitrate in bits per second - - - - - - Get the percentage of buffered data. This is a value between 0 and 100. -The @busy indicator is %TRUE when the buffering is in progress. - - - - - - - A valid #GstQuery of type GST_QUERY_BUFFERING. - - - - if buffering is busy, or %NULL - - - - a buffering percent, or %NULL - - - - - - Parse an available query, writing the format into @format, and -other results into the passed parameters, if the respective parameters -are non-%NULL - - - - - - - a GST_QUERY_BUFFERING type query #GstQuery - - - - the format to set for the @segment_start - and @segment_end values, or %NULL - - - - the start to set, or %NULL - - - - the stop to set, or %NULL - - - - estimated total amount of download - time remaining in milliseconds, or %NULL - - - - - - Extracts the buffering stats values from @query. - - - - - - - A valid #GstQuery of type GST_QUERY_BUFFERING. - - - - a buffering mode, or %NULL - - - - the average input rate, or %NULL - - - - the average output rat, or %NULL - - - - amount of buffering time left in - milliseconds, or %NULL - - - - - - Get the filter from the caps @query. The caps remains valid as long as -@query remains valid. - - - - - - - The query to parse - - - - A pointer to the caps filter - - - - - - Get the caps result from @query. The caps remains valid as long as -@query remains valid. - - - - - - - The query to parse - - - - A pointer to the caps - - - - - - Get the context from the context @query. The context remains valid as long as -@query remains valid. - - - - - - - The query to parse - - - - A pointer to store the #GstContext - - - - - - Parse a context type from an existing GST_QUERY_CONTEXT query. - - - a #gboolean indicating if the parsing succeeded. - - - - - a GST_QUERY_CONTEXT type query - - - - the context type, or %NULL - - - - - - Parse a convert query answer. Any of @src_format, @src_value, @dest_format, -and @dest_value may be %NULL, in which case that value is omitted. - - - - - - - a #GstQuery - - - - the storage for the #GstFormat of the - source value, or %NULL - - - - the storage for the source value, or %NULL - - - - the storage for the #GstFormat of the - destination value, or %NULL - - - - the storage for the destination value, - or %NULL - - - - - - Parse a duration query answer. Write the format of the duration into @format, -and the value into @duration, if the respective variables are non-%NULL. - - - - - - - a #GstQuery - - - - the storage for the #GstFormat of the duration - value, or %NULL. - - - - the storage for the total duration, or %NULL. - - - - - - Parse a latency query answer. - - - - - - - a #GstQuery - - - - storage for live or %NULL - - - - the storage for the min latency or %NULL - - - - the storage for the max latency or %NULL - - - - - - Parse the number of formats in the formats @query. - - - - - - - a #GstQuery - - - - the number of formats in this query. - - - - - - Parse an available query and get the metadata API -at @index of the metadata API array. - - - a #GType of the metadata API at @index. - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the metadata API array to read - - - - API specific parameters - - - - - - Parse an available query and get the allocator and its params -at @index of the allocator array. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the allocator array to read - - - - variable to hold the result - - - - parameters for the allocator - - - - - - Get the pool parameters in @query. - -Unref @pool with gst_object_unref() when it's not needed any more. - - - - - - - A valid #GstQuery of type GST_QUERY_ALLOCATION. - - - - index to parse - - - - the #GstBufferPool - - - - the buffer size - - - - the min buffers - - - - the max buffers - - - - - - Parse an available query and get the start and stop values stored -at the @index of the buffered ranges array. - - - a #gboolean indicating if the parsing succeeded. - - - - - a GST_QUERY_BUFFERING type query #GstQuery - - - - position in the buffered-ranges array to read - - - - the start position to set, or %NULL - - - - the stop position to set, or %NULL - - - - - - Parse the format query and retrieve the @nth format from it into -@format. If the list contains less elements than @nth, @format will be -set to GST_FORMAT_UNDEFINED. - - - - - - - a #GstQuery - - - - the nth format to retrieve. - - - - a pointer to store the nth format - - - - - - Parse an available query and get the scheduling mode -at @index of the scheduling modes array. - - - a #GstPadMode of the scheduling mode at @index. - - - - - a GST_QUERY_SCHEDULING type query #GstQuery - - - - position in the scheduling modes array to read - - - - - - Parse a position query, writing the format into @format, and the position -into @cur, if the respective parameters are non-%NULL. - - - - - - - a #GstQuery - - - - the storage for the #GstFormat of the - position values (may be %NULL) - - - - the storage for the current position (may be %NULL) - - - - - - Set the scheduling properties. - - - - - - - A valid #GstQuery of type GST_QUERY_SCHEDULING. - - - - #GstSchedulingFlags - - - - the suggested minimum size of pull requests - - - - the suggested maximum size of pull requests: - - - - the suggested alignment of pull requests - - - - - - Parse a seeking query, writing the format into @format, and -other results into the passed parameters, if the respective parameters -are non-%NULL - - - - - - - a GST_QUERY_SEEKING type query #GstQuery - - - - the format to set for the @segment_start - and @segment_end values, or %NULL - - - - the seekable flag to set, or %NULL - - - - the segment_start to set, or %NULL - - - - the segment_end to set, or %NULL - - - - - - Parse a segment query answer. Any of @rate, @format, @start_value, and -@stop_value may be %NULL, which will cause this value to be omitted. - -See gst_query_set_segment() for an explanation of the function arguments. - - - - - - - a #GstQuery - - - - the storage for the rate of the segment, or %NULL - - - - the storage for the #GstFormat of the values, - or %NULL - - - - the storage for the start value, or %NULL - - - - the storage for the stop value, or %NULL - - - - - - Parse an URI query, writing the URI into @uri as a newly -allocated string, if the respective parameters are non-%NULL. -Free the string with g_free() after usage. - - - - - - - a #GstQuery - - - - the storage for the current URI - (may be %NULL) - - - - - - Parse an URI query, writing the URI into @uri as a newly -allocated string, if the respective parameters are non-%NULL. -Free the string with g_free() after usage. - - - - - - - a #GstQuery - - - - the storage for the redirect URI - (may be %NULL) - - - - - - Parse an URI query, and set @permanent to %TRUE if there is a redirection -and it should be considered permanent. If a redirection is permanent, -applications should update their internal storage of the URI, otherwise -they should make all future requests to the original URI. - - - - - - - a #GstQuery - - - - if the URI redirection is permanent - (may be %NULL) - - - - - - Remove the metadata API at @index of the metadata API array. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the metadata API array to remove - - - - - - Remove the allocation param at @index of the allocation param array. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the allocation param array to remove - - - - - - Remove the allocation pool at @index of the allocation pool array. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the allocation pool array to remove - - - - - - Set @result as the result for the @query. - - - - - - - a GST_QUERY_ACCEPT_CAPS type query #GstQuery - - - - the result to set - - - - - - Set the results of a bitrate query. The nominal bitrate is the average -bitrate expected over the length of the stream as advertised in file -headers (or similar). - - - - - - - a GST_QUERY_BITRATE type #GstQuery - - - - the nominal bitrate in bits per second - - - - - - Set the percentage of buffered data. This is a value between 0 and 100. -The @busy indicator is %TRUE when the buffering is in progress. - - - - - - - A valid #GstQuery of type GST_QUERY_BUFFERING. - - - - if buffering is busy - - - - a buffering percent - - - - - - Set the available query result fields in @query. - - - - - - - a #GstQuery - - - - the format to set for the @start and @stop values - - - - the start to set - - - - the stop to set - - - - estimated total amount of download time remaining in - milliseconds - - - - - - Configures the buffering stats values in @query. - - - - - - - A valid #GstQuery of type GST_QUERY_BUFFERING. - - - - a buffering mode - - - - the average input rate - - - - the average output rate - - - - amount of buffering time left in milliseconds - - - - - - Set the @caps result in @query. - - - - - - - The query to use - - - - A pointer to the caps - - - - - - Answer a context query by setting the requested context. - - - - - - - a #GstQuery with query type GST_QUERY_CONTEXT - - - - the requested #GstContext - - - - - - Answer a convert query by setting the requested values. - - - - - - - a #GstQuery - - - - the source #GstFormat - - - - the source value - - - - the destination #GstFormat - - - - the destination value - - - - - - Answer a duration query by setting the requested value in the given format. - - - - - - - a #GstQuery - - - - the #GstFormat for the duration - - - - the duration of the stream - - - - - - Set the formats query result fields in @query. The number of formats passed -must be equal to @n_formats. - - - - - - - a #GstQuery - - - - the number of formats to set. - - - - A number of @GstFormats equal to @n_formats. - - - - - - Set the formats query result fields in @query. The number of formats passed -in the @formats array must be equal to @n_formats. - - - - - - - a #GstQuery - - - - the number of formats to set. - - - - an array containing @n_formats - @GstFormat values. - - - - - - - - Answer a latency query by setting the requested values in the given format. - - - - - - - a #GstQuery - - - - if there is a live element upstream - - - - the minimal latency of the upstream elements - - - - the maximal latency of the upstream elements - - - - - - Parse an available query and get the allocator and its params -at @index of the allocator array. - - - - - - - a GST_QUERY_ALLOCATION type query #GstQuery - - - - position in the allocator array to set - - - - new allocator to set - - - - parameters for the allocator - - - - - - Set the pool parameters in @query. - - - - - - - A valid #GstQuery of type GST_QUERY_ALLOCATION. - - - - index to modify - - - - the #GstBufferPool - - - - the buffer size - - - - the min buffers - - - - the max buffers - - - - - - Answer a position query by setting the requested value in the given format. - - - - - - - a #GstQuery with query type GST_QUERY_POSITION - - - - the requested #GstFormat - - - - the position to set - - - - - - Set the scheduling properties. - - - - - - - A valid #GstQuery of type GST_QUERY_SCHEDULING. - - - - #GstSchedulingFlags - - - - the suggested minimum size of pull requests - - - - the suggested maximum size of pull requests - - - - the suggested alignment of pull requests - - - - - - Set the seeking query result fields in @query. - - - - - - - a #GstQuery - - - - the format to set for the @segment_start and @segment_end values - - - - the seekable flag to set - - - - the segment_start to set - - - - the segment_end to set - - - - - - Answer a segment query by setting the requested values. The normal -playback segment of a pipeline is 0 to duration at the default rate of -1.0. If a seek was performed on the pipeline to play a different -segment, this query will return the range specified in the last seek. - -@start_value and @stop_value will respectively contain the configured -playback range start and stop values expressed in @format. -The values are always between 0 and the duration of the media and -@start_value <= @stop_value. @rate will contain the playback rate. For -negative rates, playback will actually happen from @stop_value to -@start_value. - - - - - - - a #GstQuery - - - - the rate of the segment - - - - the #GstFormat of the segment values (@start_value and @stop_value) - - - - the start value - - - - the stop value - - - - - - Answer a URI query by setting the requested URI. - - - - - - - a #GstQuery with query type GST_QUERY_URI - - - - the URI to set - - - - - - Answer a URI query by setting the requested URI redirection. - - - - - - - a #GstQuery with query type GST_QUERY_URI - - - - the URI to set - - - - - - Answer a URI query by setting the requested URI redirection -to permanent or not. - - - - - - - a #GstQuery with query type %GST_QUERY_URI - - - - whether the redirect is permanent or not - - - - - - Decreases the refcount of the query. If the refcount reaches 0, the query -will be freed. - - - - - - - a #GstQuery to decrease the refcount of. - - - - - - Get the structure of a query. This method should be called with a writable -@query so that the returned structure is guaranteed to be writable. - - - the #GstStructure of the query. The structure is - still owned by the query and will therefore be freed when the query - is unreffed. - - - - - a #GstQuery - - - - - - Modifies a pointer to a #GstQuery to point to a different #GstQuery. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -query is unreffed, the new one is reffed). - -Either @new_query or the #GstQuery pointed to by @old_query may be %NULL. - - - %TRUE if @new_query was different from @old_query - - - - - pointer to a pointer to a - #GstQuery to be replaced. - - - - pointer to a #GstQuery that will - replace the query pointed to by @old_query. - - - - - - - Standard predefined Query types - - unknown query type - - - current position in stream - - - total duration of the stream - - - latency of stream - - - current jitter of stream - - - current rate of the stream - - - seeking capabilities - - - segment start/stop positions - - - convert values between formats - - - query supported formats for convert - - - query available media for efficient seeking. - - - a custom application or element defined query. - - - query the URI of the source or sink. - - - the buffer allocation properties - - - the scheduling properties - - - the accept caps query - - - the caps query - - - wait till all serialized data is consumed downstream - - - query the pipeline-local context from - downstream or upstream (since 1.2) - - - the bitrate query (since 1.16) - - - Gets the #GstQueryTypeFlags associated with @type. - - - a #GstQueryTypeFlags. - - - - - a #GstQueryType - - - - - - Get a printable name for the given query type. Do not modify or free. - - - a reference to the static name of the query. - - - - - the query type - - - - - - Get the unique quark for the given query type. - - - the quark associated with the query type - - - - - the query type - - - - - - - #GstQueryTypeFlags indicate the aspects of the different #GstQueryType -values. You can get the type flags of a #GstQueryType with the -gst_query_type_get_flags() function. - - Set if the query can travel upstream. - - - Set if the query can travel downstream. - - - Set if the query should be serialized with data - flow. - - - - Read a 16 bit unsigned integer value in big endian format from the memory buffer. - - - - memory location - - - - - Read a 16 bit unsigned integer value in little endian format from the memory buffer. - - - - memory location - - - - - Read a 24 bit unsigned integer value in big endian format from the memory buffer. - - - - memory location - - - - - Read a 24 bit unsigned integer value in little endian format from the memory buffer. - - - - memory location - - - - - Read a 32 bit unsigned integer value in big endian format from the memory buffer. - - - - memory location - - - - - Read a 32 bit unsigned integer value in little endian format from the memory buffer. - - - - memory location - - - - - Read a 64 bit unsigned integer value in big endian format from the memory buffer. - - - - memory location - - - - - Read a 64 bit unsigned integer value in little endian format from the memory buffer. - - - - memory location - - - - - Read an 8 bit unsigned integer value from the memory buffer. - - - - memory location - - - - - - - - - - - - - - - - - - - - - - - - - - Rounds an integer value down to the next multiple of 128. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 16. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 2. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 32. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 4. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 64. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of 8. - - - - integer value to round down - - - - - Rounds an integer value down to the next multiple of @align. @align MUST be a -power of two. - - - - integrer value to round down - - - a power of two to round down to - - - - - Rounds an integer value up to the next multiple of 128. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 16. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 2. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 32. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 4. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 64. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of 8. - - - - integer value to round up - - - - - Rounds an integer value up to the next multiple of @align. @align MUST be a -power of two. - - - - integrer value to round up - - - a power of two to round up to - - - - - Element priority ranks. Defines the order in which the autoplugger (or -similar rank-picking mechanisms, such as e.g. gst_element_make_from_uri()) -will choose this element over an alternative one with the same function. - -These constants serve as a rough guidance for defining the rank of a -#GstPluginFeature. Any value is valid, including values bigger than -@GST_RANK_PRIMARY. - - will be chosen last or not at all - - - unlikely to be chosen - - - likely to be chosen - - - will be chosen first - - - - #GstReferenceTimestampMeta can be used to attach alternative timestamps and -possibly durations to a #GstBuffer. These are generally not according to -the pipeline clock and could be e.g. the NTP timestamp when the media was -captured. - -The reference is stored as a #GstCaps in @reference. Examples of valid -references would be "timestamp/x-drivername-stream" for timestamps that are locally -generated by some driver named "drivername" when generating the stream, -e.g. based on a frame counter, or "timestamp/x-ntp, host=pool.ntp.org, -port=123" for timestamps based on a specific NTP server. - - - the parent #GstMeta structure - - - - identifier for the timestamp reference. - - - - timestamp - - - - duration, or %GST_CLOCK_TIME_NONE - - - - Get the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. - - - The #GstMetaInfo - - - - - - One registry holds the metadata of a set of plugins. - -<emphasis role="bold">Design:</emphasis> - -The #GstRegistry object is a list of plugins and some functions for dealing -with them. Each #GstPlugin is matched 1-1 with a file on disk, and may or may -not be loaded at a given time. - -The primary source, at all times, of plugin information is each plugin file -itself. Thus, if an application wants information about a particular plugin, -or wants to search for a feature that satisfies given criteria, the primary -means of doing so is to load every plugin and look at the resulting -information that is gathered in the default registry. Clearly, this is a time -consuming process, so we cache information in the registry file. The format -and location of the cache file is internal to gstreamer. - -On startup, plugins are searched for in the plugin search path. The following -locations are checked in this order: - -* location from --gst-plugin-path commandline option. -* the GST_PLUGIN_PATH environment variable. -* the GST_PLUGIN_SYSTEM_PATH environment variable. -* default locations (if GST_PLUGIN_SYSTEM_PATH is not set). - Those default locations are: - `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/` - and `$prefix/libs/gstreamer-$GST_API_VERSION/`. - [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to - `$HOME/.local/share`. - -The registry cache file is loaded from -`$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin` -(where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY` -env var. One reason to change the registry location is for testing. - -For each plugin that is found in the plugin search path, there could be 3 -possibilities for cached information: - - * the cache may not contain information about a given file. - * the cache may have stale information. - * the cache may have current information. - -In the first two cases, the plugin is loaded and the cache updated. In -addition to these cases, the cache may have entries for plugins that are not -relevant to the current process. These are marked as not available to the -current process. If the cache is updated for whatever reason, it is marked -dirty. - -A dirty cache is written out at the end of initialization. Each entry is -checked to make sure the information is minimally valid. If not, the entry is -simply dropped. - -## Implementation notes: - -The "cache" and "registry" are different concepts and can represent -different sets of plugins. For various reasons, at init time, the cache is -stored in the default registry, and plugins not relevant to the current -process are marked with the %GST_PLUGIN_FLAG_CACHED bit. These plugins are -removed at the end of initialization. - - - By default GStreamer will perform scanning and rebuilding of the -registry file using a helper child process. - -Applications might want to disable this behaviour with the -gst_registry_fork_set_enabled() function, in which case new plugins -are scanned (and loaded) into the application process. - - - %TRUE if GStreamer will use the child helper process when -rebuilding the registry. - - - - - Applications might want to disable/enable spawning of a child helper process -when rebuilding the registry. See gst_registry_fork_is_enabled() for more -information. - - - - - - - whether rebuilding the registry can use a temporary child helper process. - - - - - - Retrieves the singleton plugin registry. The caller does not own a -reference on the registry, as it is alive as long as GStreamer is -initialized. - - - the #GstRegistry. - - - - - Add the feature to the registry. The feature-added signal will be emitted. - -@feature's reference count will be incremented, and any floating -reference will be removed (see gst_object_ref_sink()) - - - %TRUE on success. - -MT safe. - - - - - the registry to add the plugin to - - - - the feature to add - - - - - - Add the plugin to the registry. The plugin-added signal will be emitted. - -@plugin's reference count will be incremented, and any floating -reference will be removed (see gst_object_ref_sink()) - - - %TRUE on success. - -MT safe. - - - - - the registry to add the plugin to - - - - the plugin to add - - - - - - Checks whether a plugin feature by the given name exists in -@registry and whether its version is at least the -version required. - - - %TRUE if the feature could be found and the version is -the same as the required version or newer, and %FALSE otherwise. - - - - - a #GstRegistry - - - - the name of the feature (e.g. "oggdemux") - - - - the minimum major version number - - - - the minimum minor version number - - - - the minimum micro version number - - - - - - Runs a filter against all features of the plugins in the registry -and returns a GList with the results. -If the first flag is set, only the first match is -returned (as a list with a single object). - - - a #GList of - #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. - -MT safe. - - - - - - - registry to query - - - - the filter to use - - - - only return first match - - - - user data passed to the filter function - - - - - - Find the pluginfeature with the given name and type in the registry. - - - the pluginfeature with the - given name and type or %NULL if the plugin was not - found. gst_object_unref() after usage. - -MT safe. - - - - - the registry to search - - - - the pluginfeature name to find - - - - the pluginfeature type to find - - - - - - Find the plugin with the given name in the registry. -The plugin will be reffed; caller is responsible for unreffing. - - - the plugin with the given name - or %NULL if the plugin was not found. gst_object_unref() after - usage. - -MT safe. - - - - - the registry to search - - - - the plugin name to find - - - - - - Retrieves a #GList of #GstPluginFeature of @type. - - - a #GList of - #GstPluginFeature of @type. Use gst_plugin_feature_list_free() after use - -MT safe. - - - - - - - a #GstRegistry - - - - a #GType. - - - - - - Retrieves a #GList of features of the plugin with name @name. - - - a #GList of - #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. - - - - - - - a #GstRegistry. - - - - a plugin name. - - - - - - Returns the registry's feature list cookie. This changes -every time a feature is added or removed from the registry. - - - the feature list cookie. - - - - - the registry - - - - - - Get a copy of all plugins registered in the given registry. The refcount -of each element in the list in incremented. - - - a #GList of #GstPlugin. - Use gst_plugin_list_free() after usage. - -MT safe. - - - - - - - the registry to search - - - - - - Look up a plugin in the given registry with the given filename. -If found, plugin is reffed. - - - the #GstPlugin if found, or - %NULL if not. gst_object_unref() after usage. - - - - - the registry to look up in - - - - the name of the file to look up - - - - - - Find a #GstPluginFeature with @name in @registry. - - - a #GstPluginFeature with its refcount incremented, - use gst_object_unref() after usage. - -MT safe. - - - - - a #GstRegistry - - - - a #GstPluginFeature name - - - - - - Runs a filter against all plugins in the registry and returns a #GList with -the results. If the first flag is set, only the first match is -returned (as a list with a single object). -Every plugin is reffed; use gst_plugin_list_free() after use, which -will unref again. - - - a #GList of #GstPlugin. - Use gst_plugin_list_free() after usage. - -MT safe. - - - - - - - registry to query - - - - the filter to use - - - - only return first match - - - - user data passed to the filter function - - - - - - Remove the feature from the registry. - -MT safe. - - - - - - - the registry to remove the feature from - - - - the feature to remove - - - - - - Remove the plugin from the registry. - -MT safe. - - - - - - - the registry to remove the plugin from - - - - the plugin to remove - - - - - - Scan the given path for plugins to add to the registry. The syntax of the -path is specific to the registry. - - - %TRUE if registry changed - - - - - the registry to add found plugins to - - - - the path to scan - - - - - - - - - - - - Signals that a feature has been added to the registry (possibly -replacing a previously-added one by the same name) - - - - - - the feature that has been added - - - - - - Signals that a plugin has been added to the registry (possibly -replacing a previously-added one by the same name) - - - - - - the plugin that has been added - - - - - - - - - - - - - - - - Resource errors are for any resource used by an element: -memory, files, network connections, process space, ... -They're typically used by source and sink elements. - - a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - - - do not use this except as a placeholder for -deciding where to go while developing code. - - - used when the resource could not be found. - - - used when resource is busy. - - - used when resource fails to open for reading. - - - used when resource fails to open for writing. - - - used when resource cannot be opened for -both reading and writing, or either (but unspecified which). - - - used when the resource can't be closed. - - - used when the resource can't be read from. - - - used when the resource can't be written to. - - - used when a seek on the resource fails. - - - used when a synchronize on the resource fails. - - - used when settings can't be manipulated on. - - - used when the resource has no space left. - - - used when the resource can't be opened - due to missing authorization. - (Since: 1.2.4) - - - the number of resource error types. - - - - - - - - - - - - - - - - - - - - - - - - Constant that defines one GStreamer second. - - - - - printf format type used to debug GStreamer segments. You can use this in -combination with GStreamer's debug logging system as well as the functions -gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() -to pretty-print #GstSegment structures. -This can only be used on pointers to GstSegment structures. - - - - - - - - - A value which is guaranteed to never be returned by -gst_util_seqnum_next(). - -Can be used as a default value in variables used to store seqnum. - - - - - This macro returns the current #GstState of the element. - - - - a #GstElement to return state for. - - - - - - - - - - - - Get the conditional used to signal the completion of a state change. - - - - a #GstElement - - - - - Get a reference to the state lock of @elem. -This lock is used by the core. It is taken while getting or setting -the state, during state changes, and while finalizing. - - - - a #GstElement - - - - - Given a current state @cur and a target state @pending, calculate the next (intermediate) -#GstState. - - - - A starting #GstState - - - A target #GstState - - - - - - - - - - - - This macro returns the next #GstState of the element. - - - - a #GstElement to return the next state for. - - - - - This macro returns the currently pending #GstState of the element. - - - - a #GstElement to return the pending state for. - - - - - This macro returns the last #GstStateChangeReturn value. - - - - a #GstElement to return the last state result for. - - - - - - - - - - - - This macro returns the target #GstState of the element. - - - - a #GstElement to return the target state for. - - - - - Given a current state @cur and a next state @next, calculate the associated -#GstStateChange transition. - - - - A current state - - - A next state - - - - - Given a state transition @trans, extract the current #GstState. - - - - A #GstStateChange - - - - - Given a state transition @trans, extract the next #GstState. - - - - A #GstStateChange - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a new #GstCaps static caps from an input string. -This can be used in pad templates. - - - - the string describing the caps - - - - - Convenience macro to fill the values of a #GstStaticPadTemplate -structure. -Example: -|[<!-- language="C" --> -static GstStaticPadTemplate my_src_template = * GST_STATIC_PAD_TEMPLATE("src", GST_PAD_SRC, GST_PAD_ALWAYS, -, - GST_STATIC_CAPS_ANY); -]| - - - - the name template of the pad - - - the GstPadDirection of the pad - - - the GstPadPresence of the pad - - - the GstStaticCaps of the pad - - - - - printf format type used to debug GStreamer signed time value pointers. You -can use this in combination with GStreamer's debug logging system as well as -the functions gst_info_vasprintf(), gst_info_strdup_vprintf() and -gst_info_strdup_printf() to pretty-print signed time (pointers to -#GstClockTimeDiff or #gint64). - - - - - Format @t for the #GST_STIME_FORMAT format string. Note: @t will be -evaluated more than once. - - - - a #GstClockTimeDiff or #gint64 - - - - - A string that can be used in printf-like format strings to display a signed -#GstClockTimeDiff or #gint64 value in h:m:s format. Use GST_TIME_ARGS() to -construct the matching arguments. - -Example: -|[ -printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); -]| - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Transform an input string into a #guint32 fourcc value with host -endianness. -Caller is responsible for ensuring the input string consists of at least -four characters. - -|[ -guint32 fourcc = GST_STR_FOURCC ("MJPG"); -]| - - - - a string with at least four characters - - - - - Macro to use when a string must not be %NULL, but may be %NULL. If the string -is %NULL, "(NULL)" is printed instead. -In GStreamer printf string arguments may not be %NULL, because on some -platforms (ie Solaris) the libc crashes in that case. This includes debugging -strings. - - - - The string to check. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GstSample is a small object containing data, a type, timing and -extra arbitrary information. - - - Create a new #GstSample with the provided details. - -Free-function: gst_sample_unref - - - the new #GstSample. gst_sample_unref() - after usage. - - - - - a #GstBuffer, or %NULL - - - - a #GstCaps, or %NULL - - - - a #GstSegment, or %NULL - - - - a #GstStructure, or %NULL - - - - - - Create a copy of the given sample. This will also make a newly allocated -copy of the data the source sample contains. - - - a new copy of @buf. - - - - - a #GstSample. - - - - - - Get the buffer associated with @sample - - - the buffer of @sample or %NULL - when there is no buffer. The buffer remains valid as long as - @sample is valid. If you need to hold on to it for longer than - that, take a ref to the buffer with gst_buffer_ref(). - - - - - a #GstSample - - - - - - Get the buffer list associated with @sample - - - the buffer list of @sample or %NULL - when there is no buffer list. The buffer list remains valid as long as - @sample is valid. If you need to hold on to it for longer than - that, take a ref to the buffer list with gst_mini_object_ref (). - - - - - a #GstSample - - - - - - Get the caps associated with @sample - - - the caps of @sample or %NULL - when there is no caps. The caps remain valid as long as @sample is - valid. If you need to hold on to the caps for longer than that, - take a ref to the caps with gst_caps_ref(). - - - - - a #GstSample - - - - - - Get extra information associated with @sample. - - - the extra info of @sample. - The info remains valid as long as @sample is valid. - - - - - a #GstSample - - - - - - Get the segment associated with @sample - - - the segment of @sample. - The segment remains valid as long as @sample is valid. - - - - - a #GstSample - - - - - - Increases the refcount of the given sample by one. - - - @sample - - - - - a #GstSample - - - - - - Set the buffer associated with @sample. @sample must be writable. - - - - - - - A #GstSample - - - - A #GstBuffer - - - - - - Set the buffer list associated with @sample. @sample must be writable. - - - - - - - a #GstSample - - - - a #GstBufferList - - - - - - Set the caps associated with @sample. @sample must be writable. - - - - - - - A #GstSample - - - - A #GstCaps - - - - - - Set the info structure associated with @sample. @sample must be writable, -and @info must not have a parent set already. - - - - - - - A #GstSample - - - - A #GstStructure - - - - - - Set the segment associated with @sample. @sample must be writable. - - - - - - - A #GstSample - - - - A #GstSegment - - - - - - Decreases the refcount of the sample. If the refcount reaches 0, the -sample will be freed. - - - - - - - a #GstSample - - - - - - - The different scheduling flags. - - if seeking is possible - - - if sequential access is recommended - - - if bandwidth is limited and buffering possible (since 1.2) - - - - The different search modes. - - Only search for exact matches. - - - Search for an exact match or the element just before. - - - Search for an exact match or the element just after. - - - - Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags -can be used together. - -A non flushing seek might take some time to perform as the currently -playing data in the pipeline will not be cleared. - -An accurate seek might be slower for formats that don't have any indexes -or timestamp markers in the stream. Specifying this flag might require a -complete scan of the file in those cases. - -When performing a segment seek: after the playback of the segment completes, -no EOS will be emitted by the element that performed the seek, but a -%GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element. -When this message is posted, it is possible to send a new seek event to -continue playback. With this seek method it is possible to perform seamless -looping or simple linear editing. - -When only changing the playback rate and not the direction, the -%GST_SEEK_FLAG_INSTANT_RATE_CHANGE flag can be used for a non-flushing seek -to signal that the rate change should be applied immediately. This requires -special support in the seek handlers (e.g. demuxers) and any elements -synchronizing to the clock, and in general can't work in all cases (for example -UDP streaming where the delivery rate is controlled by a remote server). The -instant-rate-change mode supports changing the trickmode-related GST_SEEK_ flags, -but can't be used in conjunction with other seek flags that affect the new -playback position - as the playback position will not be changing. - -When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode -playback, the %GST_SEEK_FLAG_TRICKMODE flag can be used to instruct decoders -and demuxers to adjust the playback rate by skipping frames. This can improve -performance and decrease CPU usage because not all frames need to be decoded. - -Beyond that, the %GST_SEEK_FLAG_TRICKMODE_KEY_UNITS flag can be used to -request that decoders skip all frames except key units, and -%GST_SEEK_FLAG_TRICKMODE_NO_AUDIO flags can be used to request that audio -decoders do no decoding at all, and simple output silence. - -The %GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous -relevant location, and the %GST_SEEK_FLAG_SNAP_AFTER flag can be used to -select the next relevant location. If %GST_SEEK_FLAG_KEY_UNIT is specified, -the relevant location is a keyframe. If both flags are specified, the nearest -of these locations will be selected. If none are specified, the implementation is -free to select whichever it wants. - -The before and after here are in running time, so when playing backwards, -the next location refers to the one that will played in next, and not the -one that is located after in the actual source stream. - -Also see part-seeking.txt in the GStreamer design documentation for more -details on the meaning of these flags and the behaviour expected of -elements that handle them. - - no flag - - - flush pipeline - - - accurate position is requested, this might - be considerably slower for some formats. - - - seek to the nearest keyframe. This might be - faster but less accurate. - - - perform a segment seek. - - - when doing fast forward or fast reverse playback, allow - elements to skip frames instead of generating all - frames. (Since: 1.6) - - - Deprecated backward compatibility flag, replaced - by %GST_SEEK_FLAG_TRICKMODE - - - go to a location before the requested position, - if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at or before - the requested position the one at or before the seek target. - - - go to a location after the requested position, - if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at of after the - requested position. - - - go to a position near the requested position, - if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe closest - to the requested position, if both keyframes are at an equal - distance, behaves like %GST_SEEK_FLAG_SNAP_BEFORE. - - - when doing fast forward or fast reverse - playback, request that elements only decode keyframes - and skip all other content, for formats that have - keyframes. (Since: 1.6) - - - when doing fast forward or fast reverse - playback, request that audio decoder elements skip - decoding and output only gap events or silence. (Since: 1.6) - - - When doing fast forward or fast reverse - playback, request that elements only decode keyframes and - forward predicted frames and skip all other content (for example - B-Frames), for formats that have keyframes and forward predicted - frames. (Since: 1.18) - - - Signals that a rate change should be - applied immediately. Only valid if start/stop position - are GST_CLOCK_TIME_NONE, the playback direction does not change - and the seek is not flushing. (Since: 1.18) - - - - The different types of seek events. When constructing a seek event with -gst_event_new_seek() or when doing gst_segment_do_seek (). - - no change in position is required - - - absolute position is requested - - - relative position to duration is requested - - - - This helper structure holds the relevant values for tracking the region of -interest in a media file, called a segment. - -The structure can be used for two purposes: - - * performing seeks (handling seek events) - * tracking playback regions (handling newsegment events) - -The segment is usually configured by the application with a seek event which -is propagated upstream and eventually handled by an element that performs the seek. - -The configured segment is then propagated back downstream with a newsegment event. -This information is then used to clip media to the segment boundaries. - -A segment structure is initialized with gst_segment_init(), which takes a #GstFormat -that will be used as the format of the segment values. The segment will be configured -with a start value of 0 and a stop/duration of -1, which is undefined. The default -rate and applied_rate is 1.0. - -The public duration field contains the duration of the segment. When using -the segment for seeking, the start and time members should normally be left -to their default 0 value. The stop position is left to -1 unless explicitly -configured to a different value after a seek event. - -The current position in the segment should be set by changing the position -member in the structure. - -For elements that perform seeks, the current segment should be updated with the -gst_segment_do_seek() and the values from the seek event. This method will update -all the segment fields. The position field will contain the new playback position. -If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from -the position position, possibly with updated flags or rate. - -For elements that want to use #GstSegment to track the playback region, -update the segment fields with the information from the newsegment event. -The gst_segment_clip() method can be used to check and clip -the media data to the segment boundaries. - -For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time() -can be used to convert a timestamp to a value that can be used to synchronize -to the clock. This function takes into account the base as well as -any rate or applied_rate conversions. - -For elements that need to perform operations on media data in stream_time, -gst_segment_to_stream_time() can be used to convert a timestamp and the segment -info to stream time (which is always between 0 and the duration of the stream). - - - flags for this segment - - - - the playback rate of the segment is set in response to a seek - event and, without any seek, the value should be `1.0`. This - value is used by elements that synchronize buffer [running - times](additional/design/synchronisation.md#running-time) on - the clock (usually the sink elements), leading to consuming - buffers faster (for a value `> 1.0`) or slower (for `0.0 < - value < 1.0`) than normal playback speed. The rate also - defines the playback direction, meaning that when the value is - lower than `0.0`, the playback happens in reverse, and the - [stream-time](additional/design/synchronisation.md#stream-time) - is going backward. The `rate` value should never be `0.0`. - - - - The applied rate is the rate that has been applied to the stream. - The effective/resulting playback rate of a stream is - `rate * applied_rate`. - The applied rate can be set by source elements when a server is - sending the stream with an already modified playback speed - rate. Filter elements that modify the stream in a way that - modifies the playback speed should also modify the applied - rate. For example the #videorate element when its - #videorate:rate property is set will set the applied rate of - the segment it pushed downstream. Also #scaletempo applies the - input segment rate to the stream and outputs a segment with - rate=1.0 and applied_rate=<inputsegment.rate>. - - - - the unit used for all of the segment's values. - - - - the running time (plus elapsed time, see offset) of the - segment [start](GstSegment.start) ([stop](GstSegment.stop) if - rate < 0.0). - - - - the offset expresses the elapsed time (in buffer timestamps) - before a seek with its start (stop if rate < 0.0) seek type - set to #GST_SEEK_TYPE_NONE, the value is set to the position - of the segment at the time of the seek. - - - - the start time of the segment (in buffer timestamps) - [(PTS)](GstBuffer.pts), that is the timestamp of the first - buffer to output inside the segment (last one during - reverse playback). For example decoders will - [clip](gst_segment_clip) out the buffers before the start - time. - - - - the stop time of the segment (in buffer timestamps) - [(PTS)](GstBuffer.pts), that is the timestamp of the last - buffer to output inside the segment (first one during - reverse playback). For example decoders will - [clip](gst_segment_clip) out buffers after the stop time. - - - - the stream time of the segment [start](GstSegment.start) - ([stop](GstSegment.stop) if rate < 0.0). - - - - the buffer timestamp position in the segment is supposed to be - updated by elements such as sources, demuxers or parsers to - track progress by setting it to the last pushed buffer' end time - ([timestamp](GstBuffer.pts) + #GstBuffer.duration) for that - specific segment. The position is used when reconfiguring the - segment with #gst_segment_do_seek when the seek is only - updating the segment (see [offset](GstSegment.offset)). - - - - the duration of the segment is the maximum absolute difference - between #GstSegment.start and #GstSegment.stop if stop is not - set, otherwise it should be the difference between those - two values. This should be set by elements that know the - overall stream duration (like demuxers) and will be used when - seeking with #GST_SEEK_TYPE_END. - - - - - - - - - Allocate a new #GstSegment structure and initialize it using -gst_segment_init(). - -Free-function: gst_segment_free - - - a new #GstSegment, free with gst_segment_free(). - - - - - Clip the given @start and @stop values to the segment boundaries given -in @segment. @start and @stop are compared and clipped to @segment -start and stop values. - -If the function returns %FALSE, @start and @stop are known to fall -outside of @segment and @clip_start and @clip_stop are not updated. - -When the function returns %TRUE, @clip_start and @clip_stop will be -updated. If @clip_start or @clip_stop are different from @start or @stop -respectively, the region fell partially in the segment. - -Note that when @stop is -1, @clip_stop will be set to the end of the -segment. Depending on the use case, this may or may not be what you want. - - - %TRUE if the given @start and @stop times fall partially or - completely in @segment, %FALSE if the values are completely outside - of the segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the start position in the segment - - - - the stop position in the segment - - - - the clipped start position in the segment - - - - the clipped stop position in the segment - - - - - - Create a copy of given @segment. - -Free-function: gst_segment_free - - - a new #GstSegment, free with gst_segment_free(). - - - - - a #GstSegment - - - - - - Copy the contents of @src into @dest. - - - - - - - a #GstSegment - - - - a #GstSegment - - - - - - Update the segment structure with the field values of a seek event (see -gst_event_new_seek()). - -After calling this method, the segment field position and time will -contain the requested new position in the segment. The new requested -position in the segment depends on @rate and @start_type and @stop_type. - -For positive @rate, the new position in the segment is the new @segment -start field when it was updated with a @start_type different from -#GST_SEEK_TYPE_NONE. If no update was performed on @segment start position -(#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is -unmodified. - -For negative @rate, the new position in the segment is the new @segment -stop field when it was updated with a @stop_type different from -#GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the -duration of the segment will be used to update the stop position. -If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE), -@stop is ignored and @segment position is unmodified. - -The applied rate of the segment will be set to 1.0 by default. -If the caller can apply a rate change, it should update @segment -rate and applied_rate after calling this function. - -@update will be set to %TRUE if a seek should be performed to the segment -position field. This field can be %FALSE if, for example, only the @rate -has been changed but not the playback position. - - - %TRUE if the seek could be performed. - - - - - a #GstSegment structure. - - - - the rate of the segment. - - - - the format of the segment. - - - - the segment flags for the segment - - - - the seek method - - - - the seek start value - - - - the seek method - - - - the seek stop value - - - - boolean holding whether position was updated. - - - - - - Free the allocated segment @segment. - - - - - - - a #GstSegment - - - - - - The start/position fields are set to 0 and the stop/duration -fields are set to -1 (unknown). The default rate of 1.0 and no -flags are set. - -Initialize @segment to its default values. - - - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - - - Checks for two segments being equal. Equality here is defined -as perfect equality, including floating point values. - - - %TRUE if the segments are equal, %FALSE otherwise. - - - - - a #GstSegment structure. - - - - a #GstSegment structure. - - - - - - Adjust the values in @segment so that @offset is applied to all -future running-time calculations. - - - %TRUE if the segment could be updated successfully. If %FALSE is -returned, @offset is not in @segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the offset to apply in the segment - - - - - - Convert @running_time into a position in the segment so that -gst_segment_to_running_time() with that position returns @running_time. - - - the position in the segment for @running_time. This function returns --1 when @running_time is -1 or when it is not inside @segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the running_time in the segment - - - - - - Translate @running_time to the segment position using the currently configured -segment. Compared to gst_segment_position_from_running_time() this function can -return negative segment position. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -@running_time can be any value and the result of this function for values -outside of the segment is extrapolated. - -When 1 is returned, @running_time resulted in a positive position returned -in @position. - -When this function returns -1, the returned @position was < 0, and the value -in the position variable should be negated to get the real negative segment -position. - - - a 1 or -1 on success, 0 on failure. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the running-time - - - - the resulting position in the segment - - - - - - Convert @stream_time into a position in the segment so that -gst_segment_to_stream_time() with that position returns @stream_time. - - - the position in the segment for @stream_time. This function returns --1 when @stream_time is -1 or when it is not inside @segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the stream_time in the segment - - - - - - Translate @stream_time to the segment position using the currently configured -segment. Compared to gst_segment_position_from_stream_time() this function can -return negative segment position. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -@stream_time can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, @stream_time resulted in a positive position returned -in @position. - -When this function returns -1, the returned @position should be negated -to get the real negative segment position. - - - a 1 or -1 on success, 0 on failure. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the stream-time - - - - the resulting position in the segment - - - - - - Adjust the start/stop and base values of @segment such that the next valid -buffer will be one with @running_time. - - - %TRUE if the segment could be updated successfully. If %FALSE is -returned, @running_time is -1 or not in @segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the running_time in the segment - - - - - - Convert @running_time into a position in the segment so that -gst_segment_to_running_time() with that position returns @running_time. - Use gst_segment_position_from_running_time() instead. - - - the position in the segment for @running_time. This function returns --1 when @running_time is -1 or when it is not inside @segment. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the running_time in the segment - - - - - - Translate @position to the total running time using the currently configured -segment. Position is a value between @segment start and stop time. - -This function is typically used by elements that need to synchronize to the -global clock in a pipeline. The running time is a constantly increasing value -starting from 0. When gst_segment_init() is called, this value will reset to -0. - -This function returns -1 if the position is outside of @segment start and stop. - - - the position as the total running time or -1 when an invalid position -was given. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the position in the segment - - - - - - Translate @position to the total running time using the currently configured -segment. Compared to gst_segment_to_running_time() this function can return -negative running-time. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -@position can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, @position resulted in a positive running-time returned -in @running_time. - -When this function returns -1, the returned @running_time should be negated -to get the real negative running time. - - - a 1 or -1 on success, 0 on failure. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the position in the segment - - - - result running-time - - - - - - Translate @position to stream time using the currently configured -segment. The @position value must be between @segment start and -stop value. - -This function is typically used by elements that need to operate on -the stream time of the buffers it receives, such as effect plugins. -In those use cases, @position is typically the buffer timestamp or -clock time that one wants to convert to the stream time. -The stream time is always between 0 and the total duration of the -media stream. - - - the position in stream_time or -1 when an invalid position -was given. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the position in the segment - - - - - - Translate @position to the total stream time using the currently configured -segment. Compared to gst_segment_to_stream_time() this function can return -negative stream-time. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -@position can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, @position resulted in a positive stream-time returned -in @stream_time. - -When this function returns -1, the returned @stream_time should be negated -to get the real negative stream time. - - - a 1 or -1 on success, 0 on failure. - - - - - a #GstSegment structure. - - - - the format of the segment. - - - - the position in the segment - - - - result stream-time - - - - - - - Flags for the GstSegment structure. Currently mapped to the corresponding -values of the seek flags. - - no flags - - - reset the pipeline running_time to the segment - running_time - - - perform skip playback (Since: 1.6) - - - Deprecated backward compatibility flag, replaced - by @GST_SEGMENT_FLAG_TRICKMODE - - - send SEGMENT_DONE instead of EOS - - - Decode only keyframes, where - possible (Since: 1.6) - - - Decode only keyframes or forward - predicted frames, where possible (Since: 1.18) - - - Do not decode any audio, where - possible (Since: 1.6) - - - - - Try to retrieve the minimum information - available, which may be none on some platforms - (Since: 1.18) - - - Try to retrieve as much information as possible, - including source information when getting the - stack trace - - - - The possible states an element can be in. States can be changed using -gst_element_set_state() and checked using gst_element_get_state(). - - no pending state. - - - the NULL state or initial state of an element. - - - the element is ready to go to PAUSED. - - - the element is PAUSED, it is ready to accept and - process data. Sink elements however only accept one - buffer and then block. - - - the element is PLAYING, the #GstClock is running and - the data is flowing. - - - - These are the different state changes an element goes through. -%GST_STATE_NULL &rArr; %GST_STATE_PLAYING is called an upwards state change -and %GST_STATE_PLAYING &rArr; %GST_STATE_NULL a downwards state change. - - state change from NULL to READY. - * The element must check if the resources it needs are available. Device - sinks and -sources typically try to probe the device to constrain their - caps. - * The element opens the device (in case feature need to be probed). - - - state change from READY to PAUSED. - * The element pads are activated in order to receive data in PAUSED. - Streaming threads are started. - * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete - the state change when they have enough information. It is a requirement - for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change - when they receive the first buffer or %GST_EVENT_EOS (preroll). - Sinks also block the dataflow when in PAUSED. - * A pipeline resets the running_time to 0. - * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data. - - - state change from PAUSED to PLAYING. - * Most elements ignore this state change. - * The pipeline selects a #GstClock and distributes this to all the children - before setting them to PLAYING. This means that it is only allowed to - synchronize on the #GstClock in the PLAYING state. - * The pipeline uses the #GstClock and the running_time to calculate the - base_time. The base_time is distributed to all children when performing - the state change. - * Sink elements stop blocking on the preroll buffer or event and start - rendering the data. - * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed - to post %GST_MESSAGE_EOS when not in the PLAYING state. - * While streaming in PAUSED or PLAYING elements can create and remove - sometimes pads. - * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. - - - state change from PLAYING to PAUSED. - * Most elements ignore this state change. - * The pipeline calculates the running_time based on the last selected - #GstClock and the base_time. It stores this information to continue - playback when going back to the PLAYING state. - * Sinks unblock any #GstClock wait calls. - * When a sink does not have a pending buffer to play, it returns - #GST_STATE_CHANGE_ASYNC from this state change and completes the state - change when it receives a new buffer or an %GST_EVENT_EOS. - * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted - when going back to the PLAYING state. The EOS messages are queued in - #GstBin containers. - * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. - - - state change from PAUSED to READY. - * Sinks unblock any waits in the preroll. - * Elements unblock any waits on devices - * Chain or get_range functions return %GST_FLOW_FLUSHING. - * The element pads are deactivated so that streaming becomes impossible and - all streaming threads are stopped. - * The sink forgets all negotiated formats - * Elements remove all sometimes pads - - - state change from READY to NULL. - * Elements close devices - * Elements reset any internal state. - - - state change from NULL to NULL. (Since: 1.14) - - - state change from READY to READY, -This might happen when going to PAUSED asynchronously failed, in that case -elements should make sure they are in a proper, coherent READY state. (Since: 1.14) - - - state change from PAUSED to PAUSED. -This might happen when elements were in PLAYING state and 'lost state', -they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since: 1.14) - - - state change from PLAYING to PLAYING. (Since: 1.14) - - - Gets a string representing the given state transition. - - - a string with the name of the state - result. - - - - - a #GstStateChange to get the name of. - - - - - - - The possible return values from a state change function such as -gst_element_set_state(). Only @GST_STATE_CHANGE_FAILURE is a real failure. - - the state change failed - - - the state change succeeded - - - the state change will happen asynchronously - - - the state change succeeded but the element - cannot produce data in %GST_STATE_PAUSED. - This typically happens with live sources. - - - - Datastructure to initialize #GstCaps from a string description usually -used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to -instantiate a #GstCaps. - - - the cached #GstCaps - - - - a string describing a caps - - - - - - - - - Clean up the cached caps contained in @static_caps. - - - - - - - the #GstStaticCaps to clean - - - - - - Converts a #GstStaticCaps to a #GstCaps. - - - a pointer to the #GstCaps. Unref - after usage. Since the core holds an additional ref to the - returned caps, use gst_caps_make_writable() on the returned caps - to modify it. - - - - - the #GstStaticCaps to convert - - - - - - - Structure describing the #GstStaticPadTemplate. - - - the name of the template - - - - the direction of the template - - - - the presence of the template - - - - the caps of the template. - - - - Converts a #GstStaticPadTemplate into a #GstPadTemplate. - - - a new #GstPadTemplate. - - - - - the static pad template - - - - - - Gets the capabilities of the static pad template. - - - the #GstCaps of the static pad template. -Unref after usage. Since the core holds an additional -ref to the returned caps, use gst_caps_make_writable() -on the returned caps to modify it. - - - - - a #GstStaticPadTemplate to get capabilities of. - - - - - - - A high-level object representing a single stream. It might be backed, or -not, by an actual flow of data in a pipeline (#GstPad). - -A #GstStream does not care about data changes (such as decoding, encoding, -parsing,...) as long as the underlying data flow corresponds to the same -high-level flow (ex: a certain audio track). - -A #GstStream contains all the information pertinent to a stream, such as -stream-id, tags, caps, type, ... - -Elements can subclass a #GstStream for internal usage (to contain information -pertinent to streams of data). - - - Create a new #GstStream for the given @stream_id, @caps, @type -and @flags - - - The new #GstStream - - - - - the id for the new stream. If %NULL, -a new one will be automatically generated - - - - the #GstCaps of the stream - - - - the #GstStreamType of the stream - - - - the #GstStreamFlags of the stream - - - - - - Retrieve the caps for @stream, if any - - - The #GstCaps for @stream - - - - - a #GstStream - - - - - - Retrieve the current stream flags for @stream - - - The #GstStreamFlags for @stream - - - - - a #GstStream - - - - - - Returns the stream ID of @stream. - - - the stream ID of @stream. Only valid -during the lifetime of @stream. - - - - - a #GstStream - - - - - - Retrieve the stream type for @stream - - - The #GstStreamType for @stream - - - - - a #GstStream - - - - - - Retrieve the tags for @stream, if any - - - The #GstTagList for @stream - - - - - a #GstStream - - - - - - Set the caps for the #GstStream - - - - - - - a #GstStream - - - - a #GstCaps - - - - - - Set the @flags for the @stream. - - - - - - - a #GstStream - - - - the flags to set on @stream - - - - - - Set the stream type of @stream - - - - - - - a #GstStream - - - - the type to set on @stream - - - - - - Set the tags for the #GstStream - - - - - - - a #GstStream - - - - a #GstTagList - - - - - - The #GstCaps of the #GstStream. - - - - - - - The unique identifier of the #GstStream. Can only be set at construction -time. - - - - The #GstStreamType of the #GstStream. Can only be set at construction time. - - - - The #GstTagList of the #GstStream. - - - - - - - The Stream Identifier for this #GstStream - - - - - - - - - - - - - GstStream class structure - - - the parent class structure - - - - - - - - - - A collection of #GstStream that are available. - -A #GstStreamCollection will be provided by elements that can make those -streams available. Applications can use the collection to show the user -what streams are available by using %gst_stream_collection_get_stream() - -Once posted, a #GstStreamCollection is immutable. Updates are made by sending -a new #GstStreamCollection message, which may or may not share some of -the #GstStream objects from the collection it replaces. The receiver can check -the sender of a stream collection message to know which collection is -obsoleted. - -Several elements in a pipeline can provide #GstStreamCollection. - -Applications can activate streams from a collection by using the -#GST_EVENT_SELECT_STREAMS event on a pipeline, bin or element. - - - Create a new #GstStreamCollection. - - - The new #GstStreamCollection. - - - - - The stream id of the parent stream - - - - - - - - - - - - - - - - - - - - - - - Add the given @stream to the @collection. - - - %TRUE if the @stream was properly added, else %FALSE - - - - - a #GstStreamCollection - - - - the #GstStream to add - - - - - - Get the number of streams this collection contains - - - The number of streams that @collection contains - - - - - a #GstStreamCollection - - - - - - Retrieve the #GstStream with index @index from the collection. - -The caller should not modify the returned #GstStream - - - A #GstStream - - - - - a #GstStreamCollection - - - - Index of the stream to retrieve - - - - - - Returns the upstream id of the @collection. - - - The upstream id - - - - - a #GstStreamCollection - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GstStreamCollection class structure - - - the parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Stream errors are for anything related to the stream being processed: -format errors, media type errors, ... -They're typically used by decoders, demuxers, converters, ... - - a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - - - do not use this except as a placeholder for -deciding where to go while developing code. - - - use this when you do not want to implement -this functionality yet. - - - used when the element doesn't know the -stream's type. - - - used when the element doesn't handle this type -of stream. - - - used when there's no codec to handle the -stream's type. - - - used when decoding fails. - - - used when encoding fails. - - - used when demuxing fails. - - - used when muxing fails. - - - used when the stream is of the wrong format -(for example, wrong caps). - - - used when the stream is encrypted and can't be -decrypted because this is not supported by the element. - - - used when the stream is encrypted and -can't be decrypted because no suitable key is available. - - - the number of stream error types. - - - - - - - - - - - This stream has no special attributes - - - This stream is a sparse stream (e.g. a subtitle - stream), data may flow only in irregular intervals with large gaps in - between. - - - This stream should be selected by default. This - flag may be used by demuxers to signal that a stream should be selected - by default in a playback scenario. - - - This stream should not be selected by default. - This flag may be used by demuxers to signal that a stream should not - be selected by default in a playback scenario, but only if explicitly - selected by the user (e.g. an audio track for the hard of hearing or - a director's commentary track). - - - - - - - The type of a %GST_MESSAGE_STREAM_STATUS. The stream status messages inform the -application of new streaming threads and their status. - - A new thread need to be created. - - - a thread entered its loop function - - - a thread left its loop function - - - a thread is destroyed - - - a thread is started - - - a thread is paused - - - a thread is stopped - - - - #GstStreamType describes a high level classification set for -flows of data in #GstStream objects. - -Note that this is a flag, and therefore users should not assume it -will be a single value. Do not use the equality operator for checking -whether a stream is of a certain type. - - The stream is of unknown (unclassified) type. - - - The stream is of audio data - - - The stream carries video data - - - The stream is a muxed container type - - - The stream contains subtitle / subpicture data. - - - Get a descriptive string for a given #GstStreamType - - - A string describing the stream type - - - - - a #GstStreamType - - - - - - - A #GstStructure is a collection of key/value pairs. The keys are expressed as -GQuarks and the values can be of any GType. - -In addition to the key/value pairs, a #GstStructure also has a name. The name -starts with a letter and can be filled by letters, numbers and any of -"/-_.:". - -#GstStructure is used by various GStreamer subsystems to store information in -a flexible and extensible way. A #GstStructure does not have a refcount -because it usually is part of a higher level object such as #GstCaps, -#GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability -using the refcount of the parent with the gst_structure_set_parent_refcount() -method. - -A #GstStructure can be created with gst_structure_new_empty() or -gst_structure_new(), which both take a name and an optional set of key/value -pairs along with the types of the values. - -Field values can be changed with gst_structure_set_value() or -gst_structure_set(). - -Field values can be retrieved with gst_structure_get_value() or the more -convenient gst_structure_get_*() functions. - -Fields can be removed with gst_structure_remove_field() or -gst_structure_remove_fields(). - -Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not -allowed. Strings may be %NULL however. - -## The serialization format - -GstStructure serialization format serialize the GstStructure name, -keys/GType/values in a comma separated list with the structure name as first -field without value followed by separated key/value pairs in the form -`key=value`, for example: - -``` -a-structure, key=value -```` - -The values type will be inferred if not explicitly specified with the -`(GTypeName)value` syntax, for example the following struct will have one -field called 'is-string' which has the string 'true' as a value: - -``` -a-struct, field-is-string=(string)true, field-is-boolean=true -``` - -*Note*: without specifying `(string), `field-is-string` type would have been -inferred as boolean. - -*Note*: we specified `(string)` as a type even if `gchararray` is the actual -GType name as for convenience some well known types have been aliased or -abbreviated. - -To avoid specifying the type, you can give some hints to the "type system". -For example to specify a value as a double, you should add a decimal (ie. `1` -is an `int` while `1.0` is a `double`). - -*Note*: when a structure is serialized with #gst_structure_to_string, all -values are explicitly typed. - -Some types have special delimiters: - -- [GstValueArray](GST_TYPE_ARRAY) are inside curly brackets (`{` and `}`). - For example `a-structure, array={1, 2, 3}` -- Ranges are inside brackets (`[` and `]`). For example `a-structure, - range=[1, 6, 2]` 1 being the min value, 6 the maximum and 2 the step. To - specify a #GST_TYPE_INT64_RANGE you need to explicitly specify it like: - `a-structure, a-int64-range=(gint64) [1, 5]` -- [GstValueList](GST_TYPE_LIST) are inside "less and greater than" (`<` and - `>`). For example `a-structure, list=<1, 2, 3> - -Structures are delimited either by a null character `\0` or a semicolumn `;` -the latter allowing to store multiple structures in the same string (see -#GstCaps). - -Quotes are used as "default" delimiters and can be used around any types that -don't use other delimiters (for example `a-struct, i=(int)"1"`). They are use -to allow adding spaces or special characters (such as delimiters, -semicolumns, etc..) inside strings and you can use backslashes `\` to escape -characters inside them, for example: - -``` -a-struct, special="\"{[(;)]}\" can be used inside quotes" -``` - -They also allow for nested structure, such as: - -``` -a-struct, nested=(GstStructure)"nested-struct, nested=true" -``` - -> *Note*: Be aware that the current #GstCaps / #GstStructure serialization -> into string has limited support for nested #GstCaps / #GstStructure fields. -> It can only support one level of nesting. Using more levels will lead to -> unexpected behavior when using serialization features, such as -> gst_caps_to_string() or gst_value_serialize() and their counterparts. - - - the GType of a structure - - - - - - - Creates a #GstStructure from a string representation. -If end is not %NULL, a pointer to the place inside the given string -where parsing ended will be returned. - -Free-function: gst_structure_free - - - a new #GstStructure or %NULL - when the string could not be parsed. Free with - gst_structure_free() after use. - - - - - a string representation of a #GstStructure. - - - - pointer to store the end of the string in. - - - - - - Creates a new #GstStructure with the given name. Parses the -list of variable arguments and sets fields to the values listed. -Variable arguments should be passed as field name, field type, -and value. Last variable argument should be %NULL. - -Free-function: gst_structure_free - - - a new #GstStructure - - - - - name of new structure - - - - name of first field to set - - - - additional arguments - - - - - - Creates a new, empty #GstStructure with the given @name. - -See gst_structure_set_name() for constraints on the @name parameter. - -Free-function: gst_structure_free - - - a new, empty #GstStructure - - - - - name of new structure - - - - - - Creates a #GstStructure from a string representation. -If end is not %NULL, a pointer to the place inside the given string -where parsing ended will be returned. - -The current implementation of serialization will lead to unexpected results -when there are nested #GstCaps / #GstStructure deeper than one level. - -Free-function: gst_structure_free - - - a new #GstStructure or %NULL - when the string could not be parsed. Free with - gst_structure_free() after use. - - - - - a string representation of a #GstStructure - - - - - - Creates a new #GstStructure with the given name as a GQuark, followed by -fieldname quark, GType, argument(s) "triplets" in the same format as -gst_structure_id_set(). Basically a convenience wrapper around -gst_structure_new_id_empty() and gst_structure_id_set(). - -The last variable argument must be %NULL (or 0). - -Free-function: gst_structure_free - - - a new #GstStructure - - - - - name of new structure - - - - the GQuark for the name of the field to set - - - - variable arguments - - - - - - Creates a new, empty #GstStructure with the given name as a GQuark. - -Free-function: gst_structure_free - - - a new, empty #GstStructure - - - - - name of new structure - - - - - - Creates a new #GstStructure with the given @name. Structure fields -are set according to the varargs in a manner similar to -gst_structure_new(). - -See gst_structure_set_name() for constraints on the @name parameter. - -Free-function: gst_structure_free - - - a new #GstStructure - - - - - name of new structure - - - - name of first field to set - - - - variable argument list - - - - - - Tries intersecting @struct1 and @struct2 and reports whether the result -would not be empty. - - - %TRUE if intersection would not be empty - - - - - a #GstStructure - - - - a #GstStructure - - - - - - Duplicates a #GstStructure and all its fields and values. - -Free-function: gst_structure_free - - - a new #GstStructure. - - - - - a #GstStructure to duplicate - - - - - - Calls the provided function once for each field in the #GstStructure. In -contrast to gst_structure_foreach(), the function may modify the fields. -In contrast to gst_structure_map_in_place(), the field is removed from -the structure if %FALSE is returned from the function. -The structure must be mutable. - - - - - - - a #GstStructure - - - - a function to call for each field - - - - private data - - - - - - Fixate all values in @structure using gst_value_fixate(). -@structure will be modified in-place and should be writable. - - - - - - - a #GstStructure - - - - - - Fixates a #GstStructure by changing the given field with its fixated value. - - - %TRUE if the structure field could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - - - Fixates a #GstStructure by changing the given @field_name field to the given -@target boolean if that field is not fixed yet. - - - %TRUE if the structure could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - the target value of the fixation - - - - - - Fixates a #GstStructure by changing the given field to the nearest -double to @target that is a subset of the existing field. - - - %TRUE if the structure could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - the target value of the fixation - - - - - - Fixates a #GstStructure by changing the given field to the nearest -fraction to @target_numerator/@target_denominator that is a subset -of the existing field. - - - %TRUE if the structure could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - The numerator of the target value of the fixation - - - - The denominator of the target value of the fixation - - - - - - Fixates a #GstStructure by changing the given field to the nearest -integer to @target that is a subset of the existing field. - - - %TRUE if the structure could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - the target value of the fixation - - - - - - Fixates a #GstStructure by changing the given @field_name field to the given -@target string if that field is not fixed yet. - - - %TRUE if the structure could be fixated - - - - - a #GstStructure - - - - a field in @structure - - - - the target value of the fixation - - - - - - Calls the provided function once for each field in the #GstStructure. The -function must not modify the fields. Also see gst_structure_map_in_place() -and gst_structure_filter_and_map_in_place(). - - - %TRUE if the supplied function returns %TRUE For each of the fields, -%FALSE otherwise. - - - - - a #GstStructure - - - - a function to call for each field - - - - private data - - - - - - Frees a #GstStructure and all its fields and values. The structure must not -have a parent when this function is called. - - - - - - - the #GstStructure to free - - - - - - Parses the variable arguments and reads fields from @structure accordingly. -Variable arguments should be in the form field name, field type -(as a GType), pointer(s) to a variable(s) to hold the return value(s). -The last variable argument should be %NULL. - -For refcounted (mini)objects you will receive a new reference which -you must release with a suitable _unref\() when no longer needed. For -strings and boxed types you will receive a copy which you will need to -release with either g_free() or the suitable function for the boxed type. - - - %FALSE if there was a problem reading any of the fields (e.g. - because the field requested did not exist, or was of a type other - than the type specified), otherwise %TRUE. - - - - - a #GstStructure - - - - the name of the first field to read - - - - variable arguments - - - - - - This is useful in language bindings where unknown #GValue types are not -supported. This function will convert the %GST_TYPE_ARRAY into a newly -allocated #GValueArray and return it through @array. Be aware that this is -slower then getting the #GValue directly. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a %GST_TYPE_ARRAY, -this function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GValueArray - - - - - - Sets the boolean pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a boolean, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #gboolean to set - - - - - - Sets the clock time pointed to by @value corresponding to the clock time -of the given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a #GstClockTime, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GstClockTime to set - - - - - - Sets the date pointed to by @value corresponding to the date of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - -On success @value will point to a newly-allocated copy of the date which -should be freed with g_date_free() when no longer needed (note: this is -inconsistent with e.g. gst_structure_get_string() which doesn't return a -copy of the string). - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a data, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GDate to set - - - - - - Sets the datetime pointed to by @value corresponding to the datetime of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - -On success @value will point to a reference of the datetime which -should be unreffed with gst_date_time_unref() when no longer needed -(note: this is inconsistent with e.g. gst_structure_get_string() -which doesn't return a copy of the string). - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a data, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GstDateTime to set - - - - - - Sets the double pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a double, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a gdouble to set - - - - - - Sets the int pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists, -has the correct type and that the enumtype is correct. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain an enum of the given -type, this function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - the enum type of a field - - - - a pointer to an int to set - - - - - - Finds the field with the given name, and returns the type of the -value it contains. If the field is not found, G_TYPE_INVALID is -returned. - - - the #GValue of the field - - - - - a #GstStructure - - - - the name of the field - - - - - - Read the GstFlagSet flags and mask out of the structure into the -provided pointers. - - - %TRUE if the values could be set correctly. If there was no field -with @fieldname or the existing field did not contain a GstFlagSet, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a guint for the flags field - - - - a pointer to a guint for the mask field - - - - - - Sets the integers pointed to by @value_numerator and @value_denominator -corresponding to the value of the given field. Caller is responsible -for making sure the field exists and has the correct type. - - - %TRUE if the values could be set correctly. If there was no field -with @fieldname or the existing field did not contain a GstFraction, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to an int to set - - - - a pointer to an int to set - - - - - - Sets the int pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain an int, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to an int to set - - - - - - Sets the #gint64 pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a #gint64, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #gint64 to set - - - - - - This is useful in language bindings where unknown #GValue types are not -supported. This function will convert the %GST_TYPE_LIST into a newly -allocated GValueArray and return it through @array. Be aware that this is -slower then getting the #GValue directly. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a %GST_TYPE_LIST, this -function returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GValueArray - - - - - - Get the name of @structure as a string. - - - the name of the structure. - - - - - a #GstStructure - - - - - - Get the name of @structure as a GQuark. - - - the quark representing the name of the structure. - - - - - a #GstStructure - - - - - - Finds the field corresponding to @fieldname, and returns the string -contained in the field's value. Caller is responsible for making -sure the field exists and has the correct type. - -The string should not be modified, and remains valid until the next -call to a gst_structure_*() function with the given structure. - - - a pointer to the string or %NULL when the -field did not exist or did not contain a string. - - - - - a #GstStructure - - - - the name of a field - - - - - - Sets the uint pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a uint, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a uint to set - - - - - - Sets the #guint64 pointed to by @value corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - - - %TRUE if the value could be set correctly. If there was no field -with @fieldname or the existing field did not contain a #guint64, this function -returns %FALSE. - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #guint64 to set - - - - - - Parses the variable arguments and reads fields from @structure accordingly. -valist-variant of gst_structure_get(). Look at the documentation of -gst_structure_get() for more details. - - - %TRUE, or %FALSE if there was a problem reading any of the fields - - - - - a #GstStructure - - - - the name of the first field to read - - - - variable arguments - - - - - - Get the value of the field with name @fieldname. - - - the #GValue corresponding to the field with the given -name. - - - - - a #GstStructure - - - - the name of the field to get - - - - - - Check if @structure contains a field named @fieldname. - - - %TRUE if the structure contains a field with the given name - - - - - a #GstStructure - - - - the name of a field - - - - - - Check if @structure contains a field named @fieldname and with GType @type. - - - %TRUE if the structure contains a field with the given name and type - - - - - a #GstStructure - - - - the name of a field - - - - the type of a value - - - - - - Checks if the structure has the given name - - - %TRUE if @name matches the name of the structure. - - - - - a #GstStructure - - - - structure name to check for - - - - - - Parses the variable arguments and reads fields from @structure accordingly. -Variable arguments should be in the form field id quark, field type -(as a GType), pointer(s) to a variable(s) to hold the return value(s). -The last variable argument should be %NULL (technically it should be a -0 quark, but we require %NULL so compilers that support it can check for -the %NULL terminator and warn if it's not there). - -This function is just like gst_structure_get() only that it is slightly -more efficient since it saves the string-to-quark lookup in the global -quark hashtable. - -For refcounted (mini)objects you will receive a new reference which -you must release with a suitable _unref\() when no longer needed. For -strings and boxed types you will receive a copy which you will need to -release with either g_free() or the suitable function for the boxed type. - - - %FALSE if there was a problem reading any of the fields (e.g. - because the field requested did not exist, or was of a type other - than the type specified), otherwise %TRUE. - - - - - a #GstStructure - - - - the quark of the first field to read - - - - variable arguments - - - - - - Parses the variable arguments and reads fields from @structure accordingly. -valist-variant of gst_structure_id_get(). Look at the documentation of -gst_structure_id_get() for more details. - - - %TRUE, or %FALSE if there was a problem reading any of the fields - - - - - a #GstStructure - - - - the quark of the first field to read - - - - variable arguments - - - - - - Get the value of the field with GQuark @field. - - - the #GValue corresponding to the field with the given -name identifier. - - - - - a #GstStructure - - - - the #GQuark of the field to get - - - - - - Check if @structure contains a field named @field. - - - %TRUE if the structure contains a field with the given name - - - - - a #GstStructure - - - - #GQuark of the field name - - - - - - Check if @structure contains a field named @field and with GType @type. - - - %TRUE if the structure contains a field with the given name and type - - - - - a #GstStructure - - - - #GQuark of the field name - - - - the type of a value - - - - - - Identical to gst_structure_set, except that field names are -passed using the GQuark for the field name. This allows more efficient -setting of the structure if the caller already knows the associated -quark values. -The last variable argument must be %NULL. - - - - - - - a #GstStructure - - - - the GQuark for the name of the field to set - - - - variable arguments - - - - - - va_list form of gst_structure_id_set(). - - - - - - - a #GstStructure - - - - the name of the field to set - - - - variable arguments - - - - - - Sets the field with the given GQuark @field to @value. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. - - - - - - - a #GstStructure - - - - a #GQuark representing a field - - - - the new value of the field - - - - - - Sets the field with the given GQuark @field to @value. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. - - - - - - - a #GstStructure - - - - a #GQuark representing a field - - - - the new value of the field - - - - - - Intersects @struct1 and @struct2 and returns the intersection. - - - Intersection of @struct1 and @struct2 - - - - - a #GstStructure - - - - a #GstStructure - - - - - - Tests if the two #GstStructure are equal. - - - %TRUE if the two structures have the same name and field. - - - - - a #GstStructure. - - - - a #GstStructure. - - - - - - Checks if @subset is a subset of @superset, i.e. has the same -structure name and for all fields that are existing in @superset, -@subset has a value that is a subset of the value in @superset. - - - %TRUE if @subset is a subset of @superset - - - - - a #GstStructure - - - - a potentially greater #GstStructure - - - - - - Calls the provided function once for each field in the #GstStructure. In -contrast to gst_structure_foreach(), the function may modify but not delete the -fields. The structure must be mutable. - - - %TRUE if the supplied function returns %TRUE For each of the fields, -%FALSE otherwise. - - - - - a #GstStructure - - - - a function to call for each field - - - - private data - - - - - - Get the number of fields in the structure. - - - the number of fields in the structure - - - - - a #GstStructure - - - - - - Get the name of the given field number, counting from 0 onwards. - - - the name of the given field number - - - - - a #GstStructure - - - - the index to get the name of - - - - - - Removes all fields in a GstStructure. - - - - - - - a #GstStructure - - - - - - Removes the field with the given name. If the field with the given -name does not exist, the structure is unchanged. - - - - - - - a #GstStructure - - - - the name of the field to remove - - - - - - Removes the fields with the given names. If a field does not exist, the -argument is ignored. - - - - - - - a #GstStructure - - - - the name of the field to remove - - - - %NULL-terminated list of more fieldnames to remove - - - - - - va_list form of gst_structure_remove_fields(). - - - - - - - a #GstStructure - - - - the name of the field to remove - - - - %NULL-terminated list of more fieldnames to remove - - - - - - Parses the variable arguments and sets fields accordingly. Fields that -weren't already part of the structure are added as needed. -Variable arguments should be in the form field name, field type -(as a GType), value(s). The last variable argument should be %NULL. - - - - - - - a #GstStructure - - - - the name of the field to set - - - - variable arguments - - - - - - This is useful in language bindings where unknown GValue types are not -supported. This function will convert a @array to %GST_TYPE_ARRAY and set -the field specified by @fieldname. Be aware that this is slower then using -%GST_TYPE_ARRAY in a #GValue directly. - - - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GValueArray - - - - - - This is useful in language bindings where unknown GValue types are not -supported. This function will convert a @array to %GST_TYPE_LIST and set -the field specified by @fieldname. Be aware that this is slower then using -%GST_TYPE_LIST in a #GValue directly. - - - - - - - a #GstStructure - - - - the name of a field - - - - a pointer to a #GValueArray - - - - - - Sets the name of the structure to the given @name. The string -provided is copied before being used. It must not be empty, start with a -letter and can be followed by letters, numbers and any of "/-_.:". - - - - - - - a #GstStructure - - - - the new name of the structure - - - - - - Sets the parent_refcount field of #GstStructure. This field is used to -determine whether a structure is mutable or not. This function should only be -called by code implementing parent objects of #GstStructure, as described in -the MT Refcounting section of the design documents. - - - %TRUE if the parent refcount could be set. - - - - - a #GstStructure - - - - a pointer to the parent's refcount - - - - - - va_list form of gst_structure_set(). - - - - - - - a #GstStructure - - - - the name of the field to set - - - - variable arguments - - - - - - Sets the field with the given name @field to @value. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. - - - - - - - a #GstStructure - - - - the name of the field to set - - - - the new value of the field - - - - - - Sets the field with the given name @field to @value. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. The function will take ownership of @value. - - - - - - - a #GstStructure - - - - the name of the field to set - - - - the new value of the field - - - - - - Converts @structure to a human-readable string representation. - -For debugging purposes its easier to do something like this: -|[<!-- language="C" --> -GST_LOG ("structure is %" GST_PTR_FORMAT, structure); -]| -This prints the structure in human readable form. - -The current implementation of serialization will lead to unexpected results -when there are nested #GstCaps / #GstStructure deeper than one level. - -Free-function: g_free - - - a pointer to string allocated by g_malloc(). - g_free() after usage. - - - - - a #GstStructure - - - - - - Atomically modifies a pointer to point to a new structure. -The #GstStructure @oldstr_ptr is pointing to is freed and -@newstr is taken ownership over. - -Either @newstr and the value pointed to by @oldstr_ptr may be %NULL. - -It is a programming error if both @newstr and the value pointed to by -@oldstr_ptr refer to the same, non-%NULL structure. - - - %TRUE if @newstr was different from @oldstr_ptr - - - - - pointer to a place of - a #GstStructure to take - - - - a new #GstStructure - - - - - - - The type of a %GST_MESSAGE_STRUCTURE_CHANGE. - - Pad linking is starting or done. - - - Pad unlinking is starting or done. - - - - A function that will be called in gst_structure_filter_and_map_in_place(). -The function may modify @value, and the value will be removed from -the structure if %FALSE is returned. - - - %TRUE if the field should be preserved, %FALSE if it -should be removed. - - - - - the #GQuark of the field name - - - - the #GValue of the field - - - - user data - - - - - - A function that will be called in gst_structure_foreach(). The function may -not modify @value. - - - %TRUE if the foreach operation should continue, %FALSE if -the foreach operation should stop with %FALSE. - - - - - the #GQuark of the field name - - - - the #GValue of the field - - - - user data - - - - - - A function that will be called in gst_structure_map_in_place(). The function -may modify @value. - - - %TRUE if the map operation should continue, %FALSE if -the map operation should stop with %FALSE. - - - - - the #GQuark of the field name - - - - the #GValue of the field - - - - user data - - - - - - The GStreamer core provides a GstSystemClock based on the system time. -Asynchronous callbacks are scheduled from an internal thread. - -Clock implementors are encouraged to subclass this systemclock as it -implements the async notification. - -Subclasses can however override all of the important methods for sync and -async notifications to implement their own callback methods or blocking -wait operations. - - - Get a handle to the default system clock. The refcount of the -clock will be increased so you need to unref the clock after -usage. - - - the default clock. - -MT safe. - - - - - Sets the default system clock that can be obtained with -gst_system_clock_obtain(). - -This is mostly used for testing and debugging purposes when you -want to have control over the time reported by the default system -clock. - -MT safe. - - - - - - - a #GstClock - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - album containing this data (string) - -The album name as it should be displayed, e.g. 'The Jazz Guitar' - - - - - The artist of the entire album, as it should be displayed. - - - - - The artist of the entire album, as it should be sorted. - - - - - album gain in db (double) - - - - - peak of the album (double) - - - - - album containing this data, as used for sorting (string) - -The album name as it should be sorted, e.g. 'Jazz Guitar, The' - - - - - count of discs inside collection this disc belongs to (unsigned integer) - - - - - disc number inside a collection (unsigned integer) - - - - - Arbitrary application data (sample) - -Some formats allow applications to add their own arbitrary data -into files. This data is application dependent. - - - - - Name of the application used to create the media (string) - - - - - person(s) responsible for the recording (string) - -The artist name as it should be displayed, e.g. 'Jimi Hendrix' or -'The Guitar Heroes' - - - - - person(s) responsible for the recording, as used for sorting (string) - -The artist name as it should be sorted, e.g. 'Hendrix, Jimi' or -'Guitar Heroes, The' - - - - - generic file attachment (sample) (sample taglist should specify the content -type and if possible set "filename" to the file name of the -attachment) - - - - - codec the audio data is stored in (string) - - - - - number of beats per minute in audio (double) - - - - - exact or average bitrate in bits/s (unsigned integer) - - - - - codec the data is stored in (string) - - - - - free text commenting the data (string) - - - - - person(s) who composed the recording (string) - - - - - The composer's name, used for sorting (string) - - - - - conductor/performer refinement (string) - - - - - contact information (string) - - - - - container format the data is stored in (string) - - - - - copyright notice of the data (string) - - - - - URI to location where copyright details can be found (string) - - - - - date the data was created (#GDate structure) - - - - - date and time the data was created (#GstDateTime structure) - - - - - short text describing the content of the data (string) - - - - - Manufacturer of the device used to create the media (string) - - - - - Model of the device used to create the media (string) - - - - - length in GStreamer time units (nanoseconds) (unsigned 64-bit integer) - - - - - name of the person or organisation that encoded the file. May contain a -copyright message if the person or organisation also holds the copyright -(string) - -Note: do not use this field to describe the encoding application. Use -#GST_TAG_APPLICATION_NAME or #GST_TAG_COMMENT for that. - - - - - encoder used to encode this stream (string) - - - - - version of the encoder used to encode this stream (unsigned integer) - - - - - key/value text commenting the data (string) - -Must be in the form of 'key=comment' or -'key[lc]=comment' where 'lc' is an ISO-639 -language code. - -This tag is used for unknown Vorbis comment tags, -unknown APE tags and certain ID3v2 comment fields. - - - - - - - - - - - - genre this data belongs to (string) - - - - - Indicates the direction the device is pointing to when capturing -a media. It is represented as degrees in floating point representation, -0 means the geographic north, and increases clockwise (double from 0 to 360) - -See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION - - - - - The city (english name) where the media has been produced (string). - - - - - The country (english name) where the media has been produced (string). - - - - - geo elevation of where the media has been recorded or produced in meters -according to WGS84 (zero is average sea level) (double). - - - - - Represents the expected error on the horizontal positioning in -meters (double). - - - - - geo latitude location of where the media has been recorded or produced in -degrees according to WGS84 (zero at the equator, negative values for southern -latitudes) (double). - - - - - geo longitude location of where the media has been recorded or produced in -degrees according to WGS84 (zero at the prime meridian in Greenwich/UK, -negative values for western longitudes). (double). - - - - - Indicates the movement direction of the device performing the capture -of a media. It is represented as degrees in floating point representation, -0 means the geographic north, and increases clockwise (double from 0 to 360) - -See also #GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION - - - - - Speed of the capturing device when performing the capture. -Represented in m/s. (double) - -See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION - - - - - human readable descriptive location of where the media has been recorded or -produced. (string). - - - - - A location 'smaller' than GST_TAG_GEO_LOCATION_CITY that specifies better -where the media has been produced. (e.g. the neighborhood) (string). - -This tag has been added as this is how it is handled/named in XMP's -Iptc4xmpcore schema. - - - - - Groups together media that are related and spans multiple tracks. An -example are multiple pieces of a concerto. (string) - - - - - Homepage for this media (i.e. artist or movie homepage) (string) - - - - - image (sample) (sample taglist should specify the content type and preferably -also set "image-type" field as `GstTagImageType`) - - - - - Represents the 'Orientation' tag from EXIF. Defines how the image -should be rotated and mirrored for display. (string) - -This tag has a predefined set of allowed values: - "rotate-0" - "rotate-90" - "rotate-180" - "rotate-270" - "flip-rotate-0" - "flip-rotate-90" - "flip-rotate-180" - "flip-rotate-270" - -The naming is adopted according to a possible transformation to perform -on the image to fix its orientation, obviously equivalent operations will -yield the same result. - -Rotations indicated by the values are in clockwise direction and -'flip' means an horizontal mirroring. - - - - - Information about the people behind a remix and similar -interpretations of another existing piece (string) - - - - - International Standard Recording Code - see http://www.ifpi.org/isrc/ (string) - - - - - comma separated keywords describing the content (string). - - - - - ISO-639-2 or ISO-639-1 code for the language the content is in (string) - -There is utility API in libgsttag in gst-plugins-base to obtain a translated -language name from the language code: `gst_tag_get_language_name()` - - - - - Name of the language the content is in (string) - -Free-form name of the language the content is in, if a language code -is not available. This tag should not be set in addition to a language -code. It is undefined what language or locale the language name is in. - - - - - license of data (string) - - - - - URI to location where license details can be found (string) - - - - - - - - - - - - Origin of media as a URI (location, where the original of the file or stream -is hosted) (string) - - - - - The lyrics of the media (string) - - - - - maximum bitrate in bits/s (unsigned integer) - - - - - [Midi note number](http://en.wikipedia.org/wiki/Note#Note_designation_in_accordance_with_octave_name) -of the audio track. This is useful for sample instruments and in particular -for multi-samples. - - - - - minimum bitrate in bits/s (unsigned integer) - - - - - - - - - - - - nominal bitrate in bits/s (unsigned integer). The actual bitrate might be -different from this target bitrate. - - - - - organization (string) - - - - - person(s) performing (string) - - - - - image that is meant for preview purposes, e.g. small icon-sized version -(sample) (sample taglist should specify the content type) - - - - - Any private data that may be contained in tags (sample). - -It is represented by #GstSample in which #GstBuffer contains the -binary data and the sample's info #GstStructure may contain any -extra information that identifies the origin or meaning of the data. - -Private frames in ID3v2 tags ('PRIV' frames) will be represented -using this tag, in which case the GstStructure will be named -"ID3PrivateFrame" and contain a field named "owner" of type string -which contains the owner-identification string from the tag. - - - - - Name of the label or publisher (string) - - - - - reference level of track and album gain values (double) - - - - - serial number of track (unsigned integer) - - - - - - - - - - - - - - - - - - - Number of the episode within a season/show (unsigned integer) - - - - - Name of the show, used for displaying (string) - - - - - Number of the season of a show/series (unsigned integer) - - - - - Name of the show, used for sorting (string) - - - - - codec/format the subtitle data is stored in (string) - - - - - commonly used title (string) - -The title as it should be displayed, e.g. 'The Doll House' - - - - - commonly used title, as used for sorting (string) - -The title as it should be sorted, e.g. 'Doll House, The' - - - - - count of tracks inside collection this track belongs to (unsigned integer) - - - - - track gain in db (double) - - - - - track number inside a collection (unsigned integer) - - - - - peak of the track (double) - - - - - Rating attributed by a person (likely the application user). -The higher the value, the more the user likes this media -(unsigned int from 0 to 100) - - - - - version of this data (string) - - - - - codec the video data is stored in (string) - - - - - - - - - - - - Send a broadcast signal to all waiting task conds - - - - Task to broadcast - - - - - - - - - - - - - - - - - - - - - - - - - - Get access to the cond of the task. - - - - Task to get the cond of - - - - - Get access to the task lock. - - - - Task to get the lock of - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Signal the task cond - - - - Task to signal - - - - - Get access to the state of the task. - - - - Task to get the state of - - - - - Wait for the task cond to be signalled - - - - Task to wait for - - - - - printf format type used to debug GStreamer ClockTime pointers. You can use -this in combination with GStreamer's debug logging system as well as the -functions gst_info_vasprintf(), gst_info_strdup_vprintf() and -gst_info_strdup_printf() to pretty-print #GstClockTime pointers. This can -only be used on pointers to GstClockTime values. - - - - - Convert a struct timespec (see man pselect) to a #GstClockTime. - - - - the timespec to convert - - - - - Convert a GTimeVal to a #GstClockTime. - - - - the timeval to convert - - - - - Format @t for the #GST_TIME_FORMAT format string. Note: @t will be -evaluated more than once. - - - - a #GstClockTime - - - - - Convert a #GstClockTime to milliseconds (1/1000 of a second). - - - - the time - - - - - Convert a #GstClockTime to nanoseconds (1/1000000000 of a second). - - - - the time - - - - - Convert a #GstClockTime to seconds. - - - - the time - - - - - Convert a #GstClockTime to microseconds (1/1000000 of a second). - - - - the time - - - - - A string that can be used in printf-like format strings to display a -#GstClockTime value in h:m:s format. Use GST_TIME_ARGS() to construct -the matching arguments. - -Example: -|[<!-- language="C" --> -printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts)); -]| - - - - - Convert a #GstClockTime to a struct timespec (see man pselect) - - - - The #GstClockTime to convert - - - The target timespec - - - - - Convert a #GstClockTime to a GTimeVal - -> on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds, -> which is about 68 years. Expect trouble if you want to schedule stuff -> in your pipeline for 2038. - - - - The #GstClockTime to convert - - - The target timeval - - - - - Checks if @entry_type indicates that its #GstTocEntry is an alternative. - - - - The #GstTocEntryType from a #GstTocEntry - - - - - Checks if @entry_type indicates that its #GstTocEntry is a sequence. - - - - The #GstTocEntryType from a #GstTocEntry - - - - - Special value for the repeat_count set in gst_toc_entry_set_loop() or -returned by gst_toc_entry_set_loop() to indicate infinite looping. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extra tag flags used when registering tags. - - undefined flag - - - tag is meta data - - - tag is encoded - - - tag is decoded - - - number of tag flags - - - - A function that will be called in gst_tag_list_foreach(). The function may -not modify the tag list. - - - - - - - the #GstTagList - - - - a name of a tag in @list - - - - user data - - - - - - List of tags and values used to describe media metadata. - -Strings in structures must be ASCII or UTF-8 encoded. Other encodings are -not allowed. Strings must not be empty or %NULL. - - - the parent type - - - - Creates a new taglist and appends the values for the given tags. It expects -tag-value pairs like gst_tag_list_add(), and a %NULL terminator after the -last pair. The type of the values is implicit and is documented in the API -reference, but can also be queried at runtime with gst_tag_get_type(). It -is an error to pass a value of a type not matching the tag type into this -function. The tag list will make copies of any arguments passed -(e.g. strings, buffers). - -After creation you might also want to set a #GstTagScope on the returned -taglist to signal if the contained tags are global or stream tags. By -default stream scope is assumes. See gst_tag_list_set_scope(). - -Free-function: gst_tag_list_unref - - - a new #GstTagList. Free with gst_tag_list_unref() - when no longer needed. - - - - - tag - - - - %NULL-terminated list of values to set - - - - - - Creates a new empty GstTagList. - -Free-function: gst_tag_list_unref - - - An empty tag list - - - - - Deserializes a tag list. - - - a new #GstTagList, or %NULL in case of an -error. - - - - - a string created with gst_tag_list_to_string() - - - - - - Just like gst_tag_list_new(), only that it takes a va_list argument. -Useful mostly for language bindings. - -Free-function: gst_tag_list_unref - - - a new #GstTagList. Free with gst_tag_list_unref() - when no longer needed. - - - - - tag / value pairs to set - - - - - - Sets the values for the given tags using the specified mode. - - - - - - - list to set tags in - - - - the mode to use - - - - tag - - - - %NULL-terminated list of values to set - - - - - - Sets the values for the given tags using the specified mode. - - - - - - - list to set tags in - - - - the mode to use - - - - tag - - - - tag / value pairs to set - - - - - - Sets the GValues for the given tags using the specified mode. - - - - - - - list to set tags in - - - - the mode to use - - - - tag - - - - tag / GValue pairs to set - - - - - - Sets the GValue for a given tag using the specified mode. - - - - - - - list to set tags in - - - - the mode to use - - - - tag - - - - GValue for this tag - - - - - - Sets the GValues for the given tags using the specified mode. - - - - - - - list to set tags in - - - - the mode to use - - - - tag - - - - GValues to set - - - - - - Creates a new #GstTagList as a copy of the old @taglist. The new taglist -will have a refcount of 1, owned by the caller, and will be writable as -a result. - -Note that this function is the semantic equivalent of a gst_tag_list_ref() -followed by a gst_tag_list_make_writable(). If you only want to hold on to a -reference to the data, you should use gst_tag_list_ref(). - -When you are finished with the taglist, call gst_tag_list_unref() on it. - - - the new #GstTagList - - - - - a #GstTagList. - - - - - - Calls the given function for each tag inside the tag list. Note that if there -is no tag, the function won't be called at all. - - - - - - - list to iterate over - - - - function to be called for each tag - - - - user specified data - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the first date for the given tag in the taglist into the variable -pointed to by @value. Free the date with g_date_free() when it is no longer -needed. - -Free-function: g_date_free - - - %TRUE, if a date was copied, %FALSE if the tag didn't exist in the - given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - address of a GDate pointer - variable to store the result into - - - - - - Gets the date that is at the given index for the given tag in the given -list and copies it into the variable pointed to by @value. Free the date -with g_date_free() when it is no longer needed. - -Free-function: g_date_free - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the first datetime for the given tag in the taglist into the variable -pointed to by @value. Unref the date with gst_date_time_unref() when -it is no longer needed. - -Free-function: gst_date_time_unref - - - %TRUE, if a datetime was copied, %FALSE if the tag didn't exist in - the given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - address of a #GstDateTime - pointer variable to store the result into - - - - - - Gets the datetime that is at the given index for the given tag in the given -list and copies it into the variable pointed to by @value. Unref the datetime -with gst_date_time_unref() when it is no longer needed. - -Free-function: gst_date_time_unref - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Copies the first sample for the given tag in the taglist into the variable -pointed to by @sample. Free the sample with gst_sample_unref() when it is -no longer needed. You can retrieve the buffer from the sample using -gst_sample_get_buffer() and the associated caps (if any) with -gst_sample_get_caps(). - -Free-function: gst_sample_unref - - - %TRUE, if a sample was returned, %FALSE if the tag didn't exist in - the given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - address of a GstSample - pointer variable to store the result into - - - - - - Gets the sample that is at the given index for the given tag in the given -list and copies it into the variable pointed to by @sample. Free the sample -with gst_sample_unref() when it is no longer needed. You can retrieve the -buffer from the sample using gst_sample_get_buffer() and the associated -caps (if any) with gst_sample_get_caps(). - -Free-function: gst_sample_unref - - - %TRUE, if a sample was copied, %FALSE if the tag didn't exist in the - given list or if it was %NULL. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - address of a GstSample - pointer variable to store the result into - - - - - - Gets the scope of @list. - - - The scope of @list - - - - - a #GstTagList - - - - - - Copies the contents for the given tag into the value, possibly merging -multiple values into one if multiple values are associated with the tag. - -Use gst_tag_list_get_string_index (list, tag, 0, value) if you want -to retrieve the first string associated with this tag unmodified. - -The resulting string in @value will be in UTF-8 encoding and should be -freed by the caller using g_free when no longer needed. The -returned string is also guaranteed to be non-%NULL and non-empty. - -Free-function: g_free - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - -The resulting string in @value will be in UTF-8 encoding and should be -freed by the caller using g_free when no longer needed. The -returned string is also guaranteed to be non-%NULL and non-empty. - -Free-function: g_free - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Checks how many value are stored in this tag list for the given tag. - - - The number of tags stored - - - - - a taglist - - - - the tag to query - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Gets the value that is at the given index for the given tag in the given -list. - - - The GValue for the specified - entry or %NULL if the tag wasn't available or the tag - doesn't have as many entries - - - - - a #GstTagList - - - - tag to read out - - - - number of entry to read out - - - - - - Inserts the tags of the @from list into the first list using the given mode. - - - - - - - list to merge into - - - - list to merge from - - - - the mode to use - - - - - - Checks if the given taglist is empty. - - - %TRUE if the taglist is empty, otherwise %FALSE. - - - - - A #GstTagList. - - - - - - Checks if the two given taglists are equal. - - - %TRUE if the taglists are equal, otherwise %FALSE - - - - - a #GstTagList. - - - - a #GstTagList. - - - - - - Merges the two given lists into a new list. If one of the lists is %NULL, a -copy of the other is returned. If both lists are %NULL, %NULL is returned. - -Free-function: gst_tag_list_unref - - - the new list - - - - - first list to merge - - - - second list to merge - - - - the mode to use - - - - - - Get the number of tags in @list. - - - The number of tags in @list. - - - - - A #GstTagList. - - - - - - Get the name of the tag in @list at @index. - - - The name of the tag at @index. - - - - - A #GstTagList. - - - - the index - - - - - - Peeks at the value that is at the given index for the given tag in the given -list. - -The resulting string in @value will be in UTF-8 encoding and doesn't need -to be freed by the caller. The returned string is also guaranteed to -be non-%NULL and non-empty. - - - %TRUE, if a value was set, %FALSE if the tag didn't exist in the - given list. - - - - - a #GstTagList to get the tag from - - - - tag to read out - - - - number of entry to read out - - - - location for the result - - - - - - Add a reference to a #GstTagList mini object. - -From this point on, until the caller calls gst_tag_list_unref() or -gst_tag_list_make_writable(), it is guaranteed that the taglist object will -not change. To use a #GstTagList object, you must always have a refcount on -it -- either the one made implicitly by e.g. gst_tag_list_new(), or via -taking one explicitly with this function. - - - the same #GstTagList mini object. - - - - - the #GstTagList to reference - - - - - - Removes the given tag from the taglist. - - - - - - - list to remove tag from - - - - tag to remove - - - - - - Sets the scope of @list to @scope. By default the scope -of a taglist is stream scope. - - - - - - - a #GstTagList - - - - new scope for @list - - - - - - Serializes a tag list to a string. - - - a newly-allocated string, or %NULL in case of - an error. The string must be freed with g_free() when no longer - needed. - - - - - a #GstTagList - - - - - - Unref a #GstTagList, and and free all its memory when the refcount reaches 0. - - - - - - - a #GstTagList. - - - - - - Copies the contents for the given tag into the value, -merging multiple values into one if multiple values are associated -with the tag. -You must g_value_unset() the value after use. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - uninitialized #GValue to copy into - - - - list to get the tag from - - - - tag to read out - - - - - - - A function for merging multiple values of a tag used when registering -tags. - - - - - - - the destination #GValue - - - - the source #GValue - - - - - - The different tag merging modes are basically replace, overwrite and append, -but they can be seen from two directions. Given two taglists: (A) the tags -already in the element and (B) the ones that are supplied to the element ( -e.g. via gst_tag_setter_merge_tags() / gst_tag_setter_add_tags() or a -%GST_EVENT_TAG), how are these tags merged? -In the table below this is shown for the cases that a tag exists in the list -(A) or does not exists (!A) and combinations thereof. - -| merge mode | A + B | A + !B | !A + B | !A + !B | -| ----------- | ----- | ------ | ------ | ------- | -| REPLACE_ALL | B | ø | B | ø | -| REPLACE | B | A | B | ø | -| APPEND | A, B | A | B | ø | -| PREPEND | B, A | A | B | ø | -| KEEP | A | A | B | ø | -| KEEP_ALL | A | A | ø | ø | - - undefined merge mode - - - replace all tags (clear list and append) - - - replace tags - - - append tags - - - prepend tags - - - keep existing tags - - - keep all existing tags - - - the number of merge modes - - - - GstTagScope specifies if a taglist applies to the complete -medium or only to one single stream. - - tags specific to this single stream - - - global tags for the complete medium - - - - Element interface that allows setting of media metadata. - -Elements that support changing a stream's metadata will implement this -interface. Examples of such elements are 'vorbisenc', 'theoraenc' and -'id3v2mux'. - -If you just want to retrieve metadata in your application then all you -need to do is watch for tag messages on your pipeline's bus. This -interface is only for setting metadata, not for extracting it. To set tags -from the application, find tagsetter elements and set tags using e.g. -gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). Also consider -setting the #GstTagMergeMode that is used for tag events that arrive at the -tagsetter element (default mode is to keep existing tags). -The application should do that before the element goes to %GST_STATE_PAUSED. - -Elements implementing the #GstTagSetter interface often have to merge -any tags received from upstream and the tags set by the application via -the interface. This can be done like this: - -|[<!-- language="C" --> -GstTagMergeMode merge_mode; -const GstTagList *application_tags; -const GstTagList *event_tags; -GstTagSetter *tagsetter; -GstTagList *result; - -tagsetter = GST_TAG_SETTER (element); - -merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter); -application_tags = gst_tag_setter_get_tag_list (tagsetter); -event_tags = (const GstTagList *) element->event_tags; - -GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode); -GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags); -GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags); - -result = gst_tag_list_merge (application_tags, event_tags, merge_mode); - -GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); -]| - - - - Adds the given tag / value pairs on the setter using the given merge mode. -The list must be terminated with %NULL. - - - - - - - a #GstTagSetter - - - - the mode to use - - - - tag to set - - - - tag / value pairs to set - - - - - - Adds the given tag / GValue pairs on the setter using the given merge mode. -The list must be terminated with %NULL. - - - - - - - a #GstTagSetter - - - - the mode to use - - - - tag to set - - - - tag / GValue pairs to set - - - - - - Adds the given tag / GValue pair on the setter using the given merge mode. - - - - - - - a #GstTagSetter - - - - the mode to use - - - - tag to set - - - - GValue to set for the tag - - - - - - Adds the given tag / GValue pairs on the setter using the given merge mode. -The list must be terminated with %NULL. - - - - - - - a #GstTagSetter - - - - the mode to use - - - - tag to set - - - - more tag / GValue pairs to set - - - - - - Adds the given tag / value pairs on the setter using the given merge mode. -The list must be terminated with %NULL. - - - - - - - a #GstTagSetter - - - - the mode to use - - - - tag to set - - - - more tag / value pairs to set - - - - - - Returns the current list of tags the setter uses. The list should not be -modified or freed. - -This function is not thread-safe. - - - a current snapshot of the - taglist used in the setter or %NULL if none is used. - - - - - a #GstTagSetter - - - - - - Queries the mode by which tags inside the setter are overwritten by tags -from events - - - the merge mode used inside the element. - - - - - a #GstTagSetter - - - - - - Merges the given list into the setter's list using the given mode. - - - - - - - a #GstTagSetter - - - - a tag list to merge from - - - - the mode to merge with - - - - - - Reset the internal taglist. Elements should call this from within the -state-change handler. - - - - - - - a #GstTagSetter - - - - - - Sets the given merge mode that is used for adding tags from events to tags -specified by this interface. The default is #GST_TAG_MERGE_KEEP, which keeps -the tags set with this interface and discards tags from events. - - - - - - - a #GstTagSetter - - - - The mode with which tags are added - - - - - - - #GstTagSetterInterface interface. - - - parent interface type. - - - - - #GstTask is used by #GstElement and #GstPad to provide the data passing -threads in a #GstPipeline. - -A #GstPad will typically start a #GstTask to push or pull data to/from the -peer pads. Most source elements start a #GstTask to push data. In some cases -a demuxer element can start a #GstTask to pull data from a peer element. This -is typically done when the demuxer can perform random access on the upstream -peer element for improved performance. - -Although convenience functions exist on #GstPad to start/pause/stop tasks, it -might sometimes be needed to create a #GstTask manually if it is not related to -a #GstPad. - -Before the #GstTask can be run, it needs a #GRecMutex that can be set with -gst_task_set_lock(). - -The task can be started, paused and stopped with gst_task_start(), gst_task_pause() -and gst_task_stop() respectively or with the gst_task_set_state() function. - -A #GstTask will repeatedly call the #GstTaskFunction with the user data -that was provided when creating the task with gst_task_new(). While calling -the function it will acquire the provided lock. The provided lock is released -when the task pauses or stops. - -Stopping a task with gst_task_stop() will not immediately make sure the task is -not running anymore. Use gst_task_join() to make sure the task is completely -stopped and the thread is stopped. - -After creating a #GstTask, use gst_object_unref() to free its resources. This can -only be done when the task is not running anymore. - -Task functions can send a #GstMessage to send out-of-band data to the -application. The application can receive messages from the #GstBus in its -mainloop. - -For debugging purposes, the task will configure its object name as the thread -name on Linux. Please note that the object name should be configured before the -task is started; changing the object name after the task has been started, has -no effect on the thread name. - - - Create a new Task that will repeatedly call the provided @func -with @user_data as a parameter. Typically the task will run in -a new thread. - -The function cannot be changed after the task has been created. You -must create a new #GstTask to change the function. - -This function will not yet create and start a thread. Use gst_task_start() or -gst_task_pause() to create and start the GThread. - -Before the task can be used, a #GRecMutex must be configured using the -gst_task_set_lock() function. This lock will always be acquired while -@func is called. - - - A new #GstTask. - -MT safe. - - - - - The #GstTaskFunction to use - - - - User data to pass to @func - - - - the function to call when @user_data is no longer needed. - - - - - - Wait for all tasks to be stopped. This is mainly used internally -to ensure proper cleanup of internal data structures in test suites. - -MT safe. - - - - - - - Get the #GstTaskPool that this task will use for its streaming -threads. - -MT safe. - - - the #GstTaskPool used by @task. gst_object_unref() -after usage. - - - - - a #GstTask - - - - - - Get the current state of the task. - - - The #GstTaskState of the task - -MT safe. - - - - - The #GstTask to query - - - - - - Joins @task. After this call, it is safe to unref the task -and clean up the lock set with gst_task_set_lock(). - -The task will automatically be stopped with this call. - -This function cannot be called from within a task function as this -would cause a deadlock. The function will detect this and print a -g_warning. - - - %TRUE if the task could be joined. - -MT safe. - - - - - The #GstTask to join - - - - - - Pauses @task. This method can also be called on a task in the -stopped state, in which case a thread will be started and will remain -in the paused state. This function does not wait for the task to complete -the paused state. - - - %TRUE if the task could be paused. - -MT safe. - - - - - The #GstTask to pause - - - - - - Resume @task in case it was paused. If the task was stopped, it will -remain in that state and this function will return %FALSE. - - - %TRUE if the task could be resumed. - -MT safe. - - - - - The #GstTask to resume - - - - - - Call @enter_func when the task function of @task is entered. @user_data will -be passed to @enter_func and @notify will be called when @user_data is no -longer referenced. - - - - - - - The #GstTask to use - - - - a #GstTaskThreadFunc - - - - user data passed to @enter_func - - - - called when @user_data is no longer referenced - - - - - - Call @leave_func when the task function of @task is left. @user_data will -be passed to @leave_func and @notify will be called when @user_data is no -longer referenced. - - - - - - - The #GstTask to use - - - - a #GstTaskThreadFunc - - - - user data passed to @leave_func - - - - called when @user_data is no longer referenced - - - - - - Set the mutex used by the task. The mutex will be acquired before -calling the #GstTaskFunction. - -This function has to be called before calling gst_task_pause() or -gst_task_start(). - -MT safe. - - - - - - - The #GstTask to use - - - - The #GRecMutex to use - - - - - - Set @pool as the new GstTaskPool for @task. Any new streaming threads that -will be created by @task will now use @pool. - -MT safe. - - - - - - - a #GstTask - - - - a #GstTaskPool - - - - - - Sets the state of @task to @state. - -The @task must have a lock associated with it using -gst_task_set_lock() when going to GST_TASK_STARTED or GST_TASK_PAUSED or -this function will return %FALSE. - -MT safe. - - - %TRUE if the state could be changed. - - - - - a #GstTask - - - - the new task state - - - - - - Starts @task. The @task must have a lock associated with it using -gst_task_set_lock() or this function will return %FALSE. - - - %TRUE if the task could be started. - -MT safe. - - - - - The #GstTask to start - - - - - - Stops @task. This method merely schedules the task to stop and -will not wait for the task to have completely stopped. Use -gst_task_join() to stop and wait for completion. - - - %TRUE if the task could be stopped. - -MT safe. - - - - - The #GstTask to stop - - - - - - - - - the state of the task - - - - used to pause/resume the task - - - - The lock taken when iterating the task function - - - - the function executed by this task - - - - user_data passed to the task function - - - - GDestroyNotify for @user_data - - - - a flag indicating that the task is running - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A function that will repeatedly be called in the thread created by -a #GstTask. - - - - - - - user data passed to the function - - - - - - This object provides an abstraction for creating threads. The default -implementation uses a regular GThreadPool to start tasks. - -Subclasses can be made to create custom threads. - - - Create a new default task pool. The default task pool will use a regular -GThreadPool for threads. - - - a new #GstTaskPool. gst_object_unref() after usage. - - - - - Wait for all tasks to be stopped. This is mainly used internally -to ensure proper cleanup of internal data structures in test suites. - -MT safe. - - - - - - - a #GstTaskPool - - - - - - Join a task and/or return it to the pool. @id is the id obtained from -gst_task_pool_push(). - - - - - - - a #GstTaskPool - - - - the id - - - - - - Prepare the taskpool for accepting gst_task_pool_push() operations. - -MT safe. - - - - - - - a #GstTaskPool - - - - - - Start the execution of a new thread from @pool. - - - a pointer that should be used -for the gst_task_pool_join function. This pointer can be %NULL, you -must check @error to detect errors. - - - - - a #GstTaskPool - - - - the function to call - - - - data to pass to @func - - - - - - Wait for all tasks to be stopped. This is mainly used internally -to ensure proper cleanup of internal data structures in test suites. - -MT safe. - - - - - - - a #GstTaskPool - - - - - - Join a task and/or return it to the pool. @id is the id obtained from -gst_task_pool_push(). - - - - - - - a #GstTaskPool - - - - the id - - - - - - Prepare the taskpool for accepting gst_task_pool_push() operations. - -MT safe. - - - - - - - a #GstTaskPool - - - - - - Start the execution of a new thread from @pool. - - - a pointer that should be used -for the gst_task_pool_join function. This pointer can be %NULL, you -must check @error to detect errors. - - - - - a #GstTaskPool - - - - the function to call - - - - data to pass to @func - - - - - - - - - - - - - - - - - - The #GstTaskPoolClass object. - - - the parent class structure - - - - - - - - - - - a #GstTaskPool - - - - - - - - - - - - - - a #GstTaskPool - - - - - - - - - - a pointer that should be used -for the gst_task_pool_join function. This pointer can be %NULL, you -must check @error to detect errors. - - - - - a #GstTaskPool - - - - the function to call - - - - data to pass to @func - - - - - - - - - - - - - - a #GstTaskPool - - - - the id - - - - - - - - - - - - - Task function, see gst_task_pool_push(). - - - - - - - user data for the task function - - - - - - - - - The different states a task can be in - - the task is started and running - - - the task is stopped - - - the task is paused - - - - Custom GstTask thread callback functions that can be installed. - - - - - - - The #GstTask - - - - The #GThread - - - - user data - - - - - - Structure for saving a timestamp and a value. - - - timestamp of the value change - - - - the corresponding value - - - - - #GstToc functions are used to create/free #GstToc and #GstTocEntry structures. -Also they are used to convert #GstToc into #GstStructure and vice versa. - -#GstToc lets you to inform other elements in pipeline or application that playing -source has some kind of table of contents (TOC). These may be chapters, editions, -angles or other types. For example: DVD chapters, Matroska chapters or cue sheet -TOC. Such TOC will be useful for applications to display instead of just a -playlist. - -Using TOC is very easy. Firstly, create #GstToc structure which represents root -contents of the source. You can also attach TOC-specific tags to it. Then fill -it with #GstTocEntry entries by appending them to the #GstToc using -gst_toc_append_entry(), and appending subentries to a #GstTocEntry using -gst_toc_entry_append_sub_entry(). - -Note that root level of the TOC can contain only either editions or chapters. You -should not mix them together at the same level. Otherwise you will get serialization -/deserialization errors. Make sure that no one of the entries has negative start and - stop values. - -Use gst_event_new_toc() to create a new TOC #GstEvent, and gst_event_parse_toc() to -parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select #GstEvent, -and gst_event_parse_toc_select() to parse received TOC select event. The same rule for -the #GstMessage: gst_message_new_toc() to create new TOC #GstMessage, and -gst_message_parse_toc() to parse received TOC message. - -TOCs can have global scope or current scope. Global scope TOCs contain -all entries that can possibly be selected using a toc select event, and -are what an application is usually interested in. TOCs with current scope -only contain the parts of the TOC relevant to the currently selected/playing -stream; the current scope TOC is used by downstream elements such as muxers -to write correct TOC entries when transcoding files, for example. When -playing a DVD, the global TOC would contain a hierarchy of all titles, -chapters and angles, for example, while the current TOC would only contain -the chapters for the currently playing title if playback of a specific -title was requested. - -Applications and plugins should not rely on TOCs having a certain kind of -structure, but should allow for different alternatives. For example, a -simple CUE sheet embedded in a file may be presented as a flat list of -track entries, or could have a top-level edition node (or some other -alternative type entry) with track entries underneath that node; or even -multiple top-level edition nodes (or some other alternative type entries) -each with track entries underneath, in case the source file has extracted -a track listing from different sources). - - - Create a new #GstToc structure. - - - newly allocated #GstToc structure, free it - with gst_toc_unref(). - - - - - scope of this TOC - - - - - - Appends the #GstTocEntry @entry to @toc. - - - - - - - A #GstToc instance - - - - A #GstTocEntry - - - - - - - - - - - - - - - - - Find #GstTocEntry with given @uid in the @toc. - - - #GstTocEntry with specified -@uid from the @toc, or %NULL if not found. - - - - - #GstToc to search in. - - - - UID to find #GstTocEntry with. - - - - - - Gets the list of #GstTocEntry of @toc. - - - A #GList of #GstTocEntry for @entry - - - - - - - A #GstToc instance - - - - - - - - scope of @toc - - - - - a #GstToc instance - - - - - - Gets the tags for @toc. - - - A #GstTagList for @entry - - - - - A #GstToc instance - - - - - - Merge @tags into the existing tags of @toc using @mode. - - - - - - - A #GstToc instance - - - - A #GstTagList or %NULL - - - - A #GstTagMergeMode - - - - - - Set a #GstTagList with tags for the complete @toc. - - - - - - - A #GstToc instance - - - - A #GstTagList or %NULL - - - - - - - - - Create new #GstTocEntry structure. - - - newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref(). - - - - - entry type. - - - - unique ID (UID) in the whole TOC. - - - - - - Appends the #GstTocEntry @subentry to @entry. - - - - - - - A #GstTocEntry instance - - - - A #GstTocEntry - - - - - - - - @entry's entry type - - - - - a #GstTocEntry - - - - - - Get @loop_type and @repeat_count values from the @entry and write them into -appropriate storages. Loops are e.g. used by sampled instruments. GStreamer -is not automatically applying the loop. The application can process this -meta data and use it e.g. to send a seek-event to loop a section. - - - %TRUE if all non-%NULL storage pointers were filled with appropriate -values, %FALSE otherwise. - - - - - #GstTocEntry to get values from. - - - - the storage for the loop_type - value, leave %NULL if not need. - - - - the storage for the repeat_count - value, leave %NULL if not need. - - - - - - Gets the parent #GstTocEntry of @entry. - - - The parent #GstTocEntry of @entry - - - - - A #GstTocEntry instance - - - - - - Get @start and @stop values from the @entry and write them into appropriate -storages. - - - %TRUE if all non-%NULL storage pointers were filled with appropriate -values, %FALSE otherwise. - - - - - #GstTocEntry to get values from. - - - - the storage for the start value, leave - %NULL if not need. - - - - the storage for the stop value, leave - %NULL if not need. - - - - - - Gets the sub-entries of @entry. - - - A #GList of #GstTocEntry of @entry - - - - - - - A #GstTocEntry instance - - - - - - Gets the tags for @entry. - - - A #GstTagList for @entry - - - - - A #GstTocEntry instance - - - - - - Gets the parent #GstToc of @entry. - - - The parent #GstToc of @entry - - - - - A #GstTocEntry instance - - - - - - Gets the UID of @entry. - - - The UID of @entry - - - - - A #GstTocEntry instance - - - - - - - - %TRUE if @entry's type is an alternative type, otherwise %FALSE - - - - - a #GstTocEntry - - - - - - - - %TRUE if @entry's type is a sequence type, otherwise %FALSE - - - - - a #GstTocEntry - - - - - - Merge @tags into the existing tags of @entry using @mode. - - - - - - - A #GstTocEntry instance - - - - A #GstTagList or %NULL - - - - A #GstTagMergeMode - - - - - - Set @loop_type and @repeat_count values for the @entry. - - - - - - - #GstTocEntry to set values. - - - - loop_type value to set. - - - - repeat_count value to set. - - - - - - Set @start and @stop values for the @entry. - - - - - - - #GstTocEntry to set values. - - - - start value to set. - - - - stop value to set. - - - - - - Set a #GstTagList with tags for the complete @entry. - - - - - - - A #GstTocEntry instance - - - - A #GstTagList or %NULL - - - - - - - The different types of TOC entries (see #GstTocEntry). - -There are two types of TOC entries: alternatives or parts in a sequence. - - entry is an angle (i.e. an alternative) - - - entry is a version (i.e. alternative) - - - entry is an edition (i.e. alternative) - - - invalid entry type value - - - entry is a title (i.e. a part of a sequence) - - - entry is a track (i.e. a part of a sequence) - - - entry is a chapter (i.e. a part of a sequence) - - - Converts @type to a string representation. - - - Returns a human-readable string for @type. This string is - only for debugging purpose and should not be displayed in a user - interface. - - - - - a #GstTocEntryType. - - - - - - - How a #GstTocEntry should be repeated. By default, entries are played a -single time. - - single forward playback - - - repeat forward - - - repeat backward - - - repeat forward and backward - - - - The scope of a TOC. - - global TOC representing all selectable options - (this is what applications are usually interested in) - - - TOC for the currently active/selected stream - (this is a TOC representing the current stream from start to EOS, - and is what a TOC writer / muxer is usually interested in; it will - usually be a subset of the global TOC, e.g. just the chapters of - the current title, or the chapters selected for playback from the - current title) - - - - Element interface that allows setting of the TOC. - -Elements that support some kind of chapters or editions (or tracks like in -the FLAC cue sheet) will implement this interface. - -If you just want to retrieve the TOC in your application then all you -need to do is watch for TOC messages on your pipeline's bus (or you can -perform TOC query). This interface is only for setting TOC data, not for -extracting it. To set TOC from the application, find proper tocsetter element -and set TOC using gst_toc_setter_set_toc(). - -Elements implementing the #GstTocSetter interface can extend existing TOC -by getting extend UID for that (you can use gst_toc_find_entry() to retrieve it) -with any TOC entries received from downstream. - - - - Return current TOC the setter uses. The TOC should not be -modified without making it writable first. - - - TOC set, or %NULL. Unref with - gst_toc_unref() when no longer needed - - - - - a #GstTocSetter. - - - - - - Reset the internal TOC. Elements should call this from within the -state-change handler. - - - - - - - a #GstTocSetter. - - - - - - Set the given TOC on the setter. Previously set TOC will be -unreffed before setting a new one. - - - - - - - a #GstTocSetter. - - - - a #GstToc to set. - - - - - - - #GstTocSetterInterface interface. - - - parent interface type. - - - - - Tracing modules will subclass #GstTracer and register through -gst_tracer_register(). Modules can attach to various hook-types - see -gst_tracing_register_hook(). When invoked they receive hook specific -contextual data, which they must not modify. - - - Create a new tracer-factory capable of instantiating objects of the -@type and add the factory to @plugin. - - - %TRUE, if the registering succeeded, %FALSE on error - - - - - A #GstPlugin, or %NULL for a static typefind function - - - - The name for registering - - - - GType of tracer to register - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Use gst_tracer_factory_get_list() to get a list of tracer factories known to -GStreamer. - - - Gets the list of all registered tracer factories. You must free the -list using gst_plugin_feature_list_free(). - -The returned factories are sorted by factory name. - -Free-function: gst_plugin_feature_list_free - - - the list of all - registered #GstTracerFactory. - - - - - - - Get the #GType for elements managed by this factory. The type can -only be retrieved if the element factory is loaded, which can be -assured with gst_plugin_feature_load(). - - - the #GType for tracers managed by this factory or 0 if -the factory is not loaded. - - - - - factory to get managed #GType from - - - - - - - - - - - - - Tracing modules will create instances of this class to announce the data they -will log and create a log formatter. - - - Create a new tracer record. The record instance can be used to efficiently -log entries using gst_tracer_record_log(). - -The @name without the ".class" suffix will be used for the log records. -There must be fields for each value that gets logged where the field name is -the value name. The field must be a #GstStructure describing the value. The -sub structure must contain a field called 'type' of %G_TYPE_GTYPE that -contains the GType of the value. The resulting #GstTracerRecord will take -ownership of the field structures. - -The way to deal with optional values is to log an additional boolean before -the optional field, that if %TRUE signals that the optional field is valid -and %FALSE signals that the optional field should be ignored. One must still -log a placeholder value for the optional field though. Please also note, that -pointer type values must not be NULL - the underlying serialisation can not -handle that right now. - -> Please note that this is still under discussion and subject to change. - - - a new #GstTracerRecord - - - - - name of new record, must end on ".class". - - - - name of first field to set - - - - additional arguments - - - - - - Serialzes the trace event into the log. - -Right now this is using the gstreamer debug log with the level TRACE (7) and -the category "GST_TRACER". - -> Please note that this is still under discussion and subject to change. - - - - - - - the tracer-record - - - - the args as described in the spec- - - - - - - - - - - Flag that describe the value. These flags help applications processing the -logs to understand the values. - - no flags - - - the value is optional. When using this flag - one need to have an additional boolean arg before this value in the - var-args list passed to gst_tracer_record_log(). - - - the value is a combined figure, since the - start of tracing. Examples are averages or timestamps. - - - - Tracing record will contain fields that contain a measured value or extra -meta-data. One such meta data are values that tell where a measurement was -taken. This enumerating declares to which scope such a meta data field -relates to. If it is e.g. %GST_TRACER_VALUE_SCOPE_PAD, then each of the log -events may contain values for different #GstPads. - - the value is related to the process - - - the value is related to a thread - - - the value is related to an #GstElement - - - the value is related to a #GstPad - - - - The following functions allow you to detect the media type of an unknown -stream. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The data used by the caller of the typefinding function. - - - - - - - - - - - - - - - - - - - - - - Get the length of the data stream. - - - The length of the data stream, or 0 if it is not available. - - - - - The #GstTypeFind the function was called with - - - - - - Returns the @size bytes of the stream to identify beginning at offset. If -offset is a positive number, the offset is relative to the beginning of the -stream, if offset is a negative number the offset is relative to the end of -the stream. The returned memory is valid until the typefinding function -returns and must not be freed. - - - the - requested data, or %NULL if that data is not available. - - - - - - - The #GstTypeFind object the function was called with - - - - The offset - - - - The number of bytes to return - - - - - - If a #GstTypeFindFunction calls this function it suggests the caps with the -given probability. A #GstTypeFindFunction may supply different suggestions -in one call. -It is up to the caller of the #GstTypeFindFunction to interpret these values. - - - - - - - The #GstTypeFind object the function was called with - - - - The probability in percent that the suggestion is right - - - - The fixed #GstCaps to suggest - - - - - - If a #GstTypeFindFunction calls this function it suggests the caps with the -given probability. A #GstTypeFindFunction may supply different suggestions -in one call. It is up to the caller of the #GstTypeFindFunction to interpret -these values. - -This function is similar to gst_type_find_suggest(), only that instead of -passing a #GstCaps argument you can create the caps on the fly in the same -way as you can with gst_caps_new_simple(). - -Make sure you terminate the list of arguments with a %NULL argument and that -the values passed have the correct type (in terms of width in bytes when -passed to the vararg function - this applies particularly to gdouble and -guint64 arguments). - - - - - - - The #GstTypeFind object the function was called with - - - - The probability in percent that the suggestion is right - - - - the media type of the suggested caps - - - - first field of the suggested caps, or %NULL - - - - additional arguments to the suggested caps in the same format as the - arguments passed to gst_structure_new() (ie. triplets of field name, - field GType and field value) - - - - - - Registers a new typefind function to be used for typefinding. After -registering this function will be available for typefinding. -This function is typically called during an element's plugin initialization. - - - %TRUE on success, %FALSE otherwise - - - - - A #GstPlugin, or %NULL for a static typefind function - - - - The name for registering - - - - The rank (or importance) of this typefind function - - - - The #GstTypeFindFunction to use - - - - Optional comma-separated list of extensions - that could belong to this type - - - - Optionally the caps that could be returned when typefinding - succeeds - - - - Optional user data. This user data must be available until the plugin - is unloaded. - - - - a #GDestroyNotify that will be called on @data when the plugin - is unloaded. - - - - - - - These functions allow querying information about registered typefind -functions. How to create and register these functions is described in -the section <link linkend="gstreamer-Writing-typefind-functions"> -"Writing typefind functions"</link>. - -The following example shows how to write a very simple typefinder that -identifies the given data. You can get quite a bit more complicated than -that though. -|[<!-- language="C" --> - typedef struct { - guint8 *data; - guint size; - guint probability; - GstCaps *data; - } MyTypeFind; - static void - my_peek (gpointer data, gint64 offset, guint size) - { - MyTypeFind *find = (MyTypeFind *) data; - if (offset &gt;= 0 &amp;&amp; offset + size &lt;= find->size) { - return find->data + offset; - } - return NULL; - } - static void - my_suggest (gpointer data, guint probability, GstCaps *caps) - { - MyTypeFind *find = (MyTypeFind *) data; - if (probability &gt; find->probability) { - find->probability = probability; - gst_caps_replace (&amp;find->caps, caps); - } - } - static GstCaps * - find_type (guint8 *data, guint size) - { - GList *walk, *type_list; - MyTypeFind find = {data, size, 0, NULL}; - GstTypeFind gst_find = {my_peek, my_suggest, &amp;find, }; - walk = type_list = gst_type_find_factory_get_list (); - while (walk) { - GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data); - walk = g_list_next (walk) - gst_type_find_factory_call_function (factory, &amp;gst_find); - } - g_list_free (type_list); - return find.caps; - }; -]| - - - Gets the list of all registered typefind factories. You must free the -list using gst_plugin_feature_list_free(). - -The returned factories are sorted by highest rank first, and then by -factory name. - -Free-function: gst_plugin_feature_list_free - - - the list of all - registered #GstTypeFindFactory. - - - - - - - Calls the #GstTypeFindFunction associated with this factory. - - - - - - - A #GstTypeFindFactory - - - - a properly setup #GstTypeFind entry. The get_data - and suggest_type members must be set. - - - - - - Gets the #GstCaps associated with a typefind factory. - - - the #GstCaps associated with this factory - - - - - A #GstTypeFindFactory - - - - - - Gets the extensions associated with a #GstTypeFindFactory. The returned -array should not be changed. If you need to change stuff in it, you should -copy it using g_strdupv(). This function may return %NULL to indicate -a 0-length list. - - - - a %NULL-terminated array of extensions associated with this factory - - - - - - - A #GstTypeFindFactory - - - - - - Check whether the factory has a typefind function. Typefind factories -without typefind functions are a last-effort fallback mechanism to -e.g. assume a certain media type based on the file extension. - - - %TRUE if the factory has a typefind functions set, otherwise %FALSE - - - - - A #GstTypeFindFactory - - - - - - - - - - A function that will be called by typefinding. - - - - - - - A #GstTypeFind structure - - - - optional data to pass to the function - - - - - - The probability of the typefind function. Higher values have more certainty -in doing a reliable typefind. - - type undetected. - - - unlikely typefind. - - - possible type detected. - - - likely a type was detected. - - - nearly certain that a type was detected. - - - very certain a type was detected. - - - - - - - - - - - Different URI-related errors that can occur. - - The protocol is not supported - - - There was a problem with the URI - - - Could not set or change the URI because the - URI handler was in a state where that is not possible or not permitted - - - There was a problem with the entity that - the URI references - - - - - - - - - - The #GstURIHandler is an interface that is implemented by Source and Sink -#GstElement to unify handling of URI. - -An application can use the following functions to quickly get an element -that handles the given URI for reading or writing -(gst_element_make_from_uri()). - -Source and Sink plugins should implement this interface when possible. - - - Gets the currently handled URI. - - - the URI currently handled by - the @handler. Returns %NULL if there are no URI currently - handled. The returned string must be freed with g_free() when no - longer needed. - - - - - A #GstURIHandler - - - - - - Tries to set the URI of the given handler. - - - %TRUE if the URI was set successfully, else %FALSE. - - - - - A #GstURIHandler - - - - URI to set - - - - - - Gets the list of protocols supported by @handler. This list may not be -modified. - - - the - supported protocols. Returns %NULL if the @handler isn't - implemented properly, or the @handler doesn't support any - protocols. - - - - - - - A #GstURIHandler. - - - - - - Gets the currently handled URI. - - - the URI currently handled by - the @handler. Returns %NULL if there are no URI currently - handled. The returned string must be freed with g_free() when no - longer needed. - - - - - A #GstURIHandler - - - - - - Gets the type of the given URI handler - - - the #GstURIType of the URI handler. -Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. - - - - - A #GstURIHandler. - - - - - - Tries to set the URI of the given handler. - - - %TRUE if the URI was set successfully, else %FALSE. - - - - - A #GstURIHandler - - - - URI to set - - - - - - - Any #GstElement using this interface should implement these methods. - - - The parent interface type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the URI currently handled by - the @handler. Returns %NULL if there are no URI currently - handled. The returned string must be freed with g_free() when no - longer needed. - - - - - A #GstURIHandler - - - - - - - - - - %TRUE if the URI was set successfully, else %FALSE. - - - - - A #GstURIHandler - - - - URI to set - - - - - - - - The different types of URI direction. - - The URI direction is unknown - - - The URI is a consumer. - - - The URI is a producer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Value for #GstUri<!-- -->.port to indicate no port number. - - - - - Tests if the type direction is valid. - - - - A #GstURIType - - - - - Constant that defines one GStreamer microsecond. - - - - - A #GstUri object can be used to parse and split a URI string into its -constituent parts. Two #GstUri objects can be joined to make a new #GstUri -using the algorithm described in RFC3986. - - - Creates a new #GstUri object with the given URI parts. The path and query -strings will be broken down into their elements. All strings should not be -escaped except where indicated. - - - A new #GstUri object. - - - - - The scheme for the new URI. - - - - The user-info for the new URI. - - - - The host name for the new URI. - - - - The port number for the new URI or %GST_URI_NO_PORT. - - - - The path for the new URI with '/' separating path - elements. - - - - The query string for the new URI with '&' separating - query elements. Elements containing '&' characters - should encode them as "&percnt;26". - - - - The fragment name for the new URI. - - - - - - Append a path onto the end of the path in the URI. The path is not -normalized, call #gst_uri_normalize() to normalize the path. - - - %TRUE if the path was appended successfully. - - - - - The #GstUri to modify. - - - - Relative path to append to the end of the current path. - - - - - - Append a single path segment onto the end of the URI path. - - - %TRUE if the path was appended successfully. - - - - - The #GstUri to modify. - - - - The path segment string to append to the URI path. - - - - - - Compares two #GstUri objects to see if they represent the same normalized -URI. - - - %TRUE if the normalized versions of the two URI's would be equal. - - - - - First #GstUri to compare. - - - - Second #GstUri to compare. - - - - - - Like gst_uri_from_string() but also joins with a base URI. - - - A new #GstUri object. - - - - - The base URI to join the new URI with. - - - - The URI string to parse. - - - - - - Get the fragment name from the URI or %NULL if it doesn't exist. -If @uri is %NULL then returns %NULL. - - - The host name from the #GstUri object or %NULL. - - - - - This #GstUri object. - - - - - - Get the host name from the URI or %NULL if it doesn't exist. -If @uri is %NULL then returns %NULL. - - - The host name from the #GstUri object or %NULL. - - - - - This #GstUri object. - - - - - - Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". -Hash table returned by this API is a list of "key-value" pairs, and the each -pair is generated by splitting "URI fragment" per "&" sub-delims, then "key" -and "value" are split by "=" sub-delims. The "key" returned by this API may -be undefined keyword by standard. -A value may be %NULL to indicate that the key should appear in the fragment -string in the URI, but does not have a value. Free the returned #GHashTable -with #g_hash_table_unref() when it is no longer required. -Modifying this hash table does not affect the fragment in the URI. - -See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/ - - - The - fragment hash table from the URI. - - - - - - - - The #GstUri to get the fragment table from. - - - - - - Extract the path string from the URI object. - - - The path from the URI. Once finished - with the string should be g_free()'d. - - - - - The #GstUri to get the path from. - - - - - - Get a list of path segments from the URI. - - - A #GList of path segment - strings or %NULL if no path segments are available. Free the list - when no longer needed with g_list_free_full(list, g_free). - - - - - - - The #GstUri to get the path from. - - - - - - Extract the path string from the URI object as a percent encoded URI path. - - - The path from the URI. Once finished - with the string should be g_free()'d. - - - - - The #GstUri to get the path from. - - - - - - Get the port number from the URI or %GST_URI_NO_PORT if it doesn't exist. -If @uri is %NULL then returns %GST_URI_NO_PORT. - - - The port number from the #GstUri object or %GST_URI_NO_PORT. - - - - - This #GstUri object. - - - - - - Get a list of the query keys from the URI. - - - A list of keys from - the URI query. Free the list with g_list_free(). - - - - - - - The #GstUri to examine. - - - - - - Get a percent encoded URI query string from the @uri. - - - A percent encoded query string. Use - g_free() when no longer needed. - - - - - The #GstUri to get the query string from. - - - - - - Get the query table from the URI. Keys and values in the table are freed -with g_free when they are deleted. A value may be %NULL to indicate that -the key should appear in the query string in the URI, but does not have a -value. Free the returned #GHashTable with #g_hash_table_unref() when it is -no longer required. Modifying this hash table will modify the query in the -URI. - - - The query - hash table from the URI. - - - - - - - - The #GstUri to get the query table from. - - - - - - Get the value associated with the @query_key key. Will return %NULL if the -key has no value or if the key does not exist in the URI query table. Because -%NULL is returned for both missing keys and keys with no value, you should -use gst_uri_query_has_key() to determine if a key is present in the URI -query. - - - The value for the given key, or %NULL if not found. - - - - - The #GstUri to examine. - - - - The key to lookup. - - - - - - Get the scheme name from the URI or %NULL if it doesn't exist. -If @uri is %NULL then returns %NULL. - - - The scheme from the #GstUri object or %NULL. - - - - - This #GstUri object. - - - - - - Get the userinfo (usually in the form "username:password") from the URI -or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. - - - The userinfo from the #GstUri object or %NULL. - - - - - This #GstUri object. - - - - - - Tests the @uri to see if it is normalized. A %NULL @uri is considered to be -normalized. - - - TRUE if the URI is normalized or is %NULL. - - - - - The #GstUri to test to see if it is normalized. - - - - - - Check if it is safe to write to this #GstUri. - -Check if the refcount of @uri is exactly 1, meaning that no other -reference exists to the #GstUri and that the #GstUri is therefore writable. - -Modification of a #GstUri should only be done after verifying that it is -writable. - - - %TRUE if it is safe to write to the object. - - - - - The #GstUri object to test. - - - - - - Join a reference URI onto a base URI using the method from RFC 3986. -If either URI is %NULL then the other URI will be returned with the ref count -increased. - - - A #GstUri which represents the base - with the reference URI joined on. - - - - - The base URI to join another to. - - - - The reference URI to join onto the - base URI. - - - - - - Make the #GstUri writable. - -Checks if @uri is writable, and if so the original object is returned. If -not, then a writable copy is made and returned. This gives away the -reference to @uri and returns a reference to the new #GstUri. -If @uri is %NULL then %NULL is returned. - - - A writable version of @uri. - - - - - The #GstUri object to make writable. - - - - - - Like gst_uri_new(), but joins the new URI onto a base URI. - - - The new URI joined onto @base. - - - - - The base URI to join the new URI to. - - - - The scheme for the new URI. - - - - The user-info for the new URI. - - - - The host name for the new URI. - - - - The port number for the new URI or %GST_URI_NO_PORT. - - - - The path for the new URI with '/' separating path - elements. - - - - The query string for the new URI with '&' separating - query elements. Elements containing '&' characters - should encode them as "&percnt;26". - - - - The fragment name for the new URI. - - - - - - Normalization will remove extra path segments ("." and "..") from the URI. It -will also convert the scheme and host name to lower case and any -percent-encoded values to uppercase. - -The #GstUri object must be writable. Check with gst_uri_is_writable() or use -gst_uri_make_writable() first. - - - TRUE if the URI was modified. - - - - - The #GstUri to normalize. - - - - - - Check if there is a query table entry for the @query_key key. - - - %TRUE if @query_key exists in the URI query table. - - - - - The #GstUri to examine. - - - - The key to lookup. - - - - - - Remove an entry from the query table by key. - - - %TRUE if the key existed in the table and was removed. - - - - - The #GstUri to modify. - - - - The key to remove. - - - - - - Sets the fragment string in the URI. Use a value of %NULL in @fragment to -unset the fragment string. - - - %TRUE if the fragment was set/unset successfully. - - - - - The #GstUri to modify. - - - - The fragment string to set. - - - - - - Set or unset the host for the URI. - - - %TRUE if the host was set/unset successfully. - - - - - The #GstUri to modify. - - - - The new host string to set or %NULL to unset. - - - - - - Sets or unsets the path in the URI. - - - %TRUE if the path was set successfully. - - - - - The #GstUri to modify. - - - - The new path to set with path segments separated by '/', or use %NULL - to unset the path. - - - - - - Replace the path segments list in the URI. - - - %TRUE if the path segments were set successfully. - - - - - The #GstUri to modify. - - - - The new - path list to set. - - - - - - - - Sets or unsets the path in the URI. - - - %TRUE if the path was set successfully. - - - - - The #GstUri to modify. - - - - The new percent encoded path to set with path segments separated by -'/', or use %NULL to unset the path. - - - - - - Set or unset the port number for the URI. - - - %TRUE if the port number was set/unset successfully. - - - - - The #GstUri to modify. - - - - The new port number to set or %GST_URI_NO_PORT to unset. - - - - - - Sets or unsets the query table in the URI. - - - %TRUE if the query table was set successfully. - - - - - The #GstUri to modify. - - - - The new percent encoded query string to use to populate the query - table, or use %NULL to unset the query table. - - - - - - Set the query table to use in the URI. The old table is unreferenced and a -reference to the new one is used instead. A value if %NULL for @query_table -will remove the query string from the URI. - - - %TRUE if the new table was successfully used for the query table. - - - - - The #GstUri to modify. - - - - The new - query table to use. - - - - - - - - - This inserts or replaces a key in the query table. A @query_value of %NULL -indicates that the key has no associated value, but will still be present in -the query string. - - - %TRUE if the query table was successfully updated. - - - - - The #GstUri to modify. - - - - The key for the query entry. - - - - The value for the key. - - - - - - Set or unset the scheme for the URI. - - - %TRUE if the scheme was set/unset successfully. - - - - - The #GstUri to modify. - - - - The new scheme to set or %NULL to unset the scheme. - - - - - - Set or unset the user information for the URI. - - - %TRUE if the user information was set/unset successfully. - - - - - The #GstUri to modify. - - - - The new user-information string to set or %NULL to unset. - - - - - - Convert the URI to a string. - -Returns the URI as held in this object as a #gchar* nul-terminated string. -The caller should g_free() the string once they are finished with it. -The string is put together as described in RFC 3986. - - - The string version of the URI. - - - - - This #GstUri to convert to a string. - - - - - - Constructs a URI for a given valid protocol and location. - -Free-function: g_free - Use GstURI instead. - - - a new string for this URI. Returns %NULL if the - given URI protocol is not valid, or the given location is %NULL. - - - - - Protocol for URI - - - - Location for URI - - - - - - Parses a URI string into a new #GstUri object. Will return NULL if the URI -cannot be parsed. - - - A new #GstUri object, or NULL. - - - - - The URI string to parse. - - - - - - Parses a URI string into a new #GstUri object. Will return NULL if the URI -cannot be parsed. This is identical to gst_uri_from_string() except that -the userinfo and fragment components of the URI will not be unescaped while -parsing. - -Use this when you need to extract a username and password from the userinfo -such as https://user:password@example.com since either may contain -a URI-escaped ':' character. gst_uri_from_string() will unescape the entire -userinfo component, which will make it impossible to know which ':' -delineates the username and password. - -The same applies to the fragment component of the URI, such as -https://example.com/path#fragment which may contain a URI-escaped '#'. - - - A new #GstUri object, or NULL. - - - - - The URI string to parse. - - - - - - Extracts the location out of a given valid URI, ie. the protocol and "://" -are stripped from the URI, which means that the location returned includes -the hostname if one is specified. The returned string must be freed using -g_free(). - -Free-function: g_free - - - the location for this URI. Returns - %NULL if the URI isn't valid. If the URI does not contain a location, an - empty string is returned. - - - - - A URI string - - - - - - Extracts the protocol out of a given valid URI. The returned string must be -freed using g_free(). - - - The protocol for this URI. - - - - - A URI string - - - - - - Checks if the protocol of a given valid URI matches @protocol. - - - %TRUE if the protocol matches. - - - - - a URI string - - - - a protocol string (e.g. "http") - - - - - - Tests if the given string is a valid URI identifier. URIs start with a valid -scheme followed by ":" and maybe a string identifying the location. - - - %TRUE if the string is a valid URI - - - - - A URI string - - - - - - This is a convenience function to join two URI strings and return the result. -The returned string should be g_free()'d after use. - - - A string representing the percent-encoded join of - the two URIs. - - - - - The percent-encoded base URI. - - - - The percent-encoded reference URI to join to the @base_uri. - - - - - - Checks if an element exists that supports the given URI protocol. Note -that a positive return value does not imply that a subsequent call to -gst_element_make_from_uri() is guaranteed to work. - - - %TRUE - - - - - Whether to check for a source or a sink - - - - Protocol that should be checked for (e.g. "http" or "smb") - - - - - - Tests if the given string is a valid protocol identifier. Protocols -must consist of alphanumeric characters, '+', '-' and '.' and must -start with a alphabetic character. See RFC 3986 Section 3.1. - - - %TRUE if the string is a valid protocol identifier, %FALSE otherwise. - - - - - A string - - - - - - - Indicates that the first value provided to a comparison function -(gst_value_compare()) is equal to the second one. - - - - - Indicates that the first value provided to a comparison function -(gst_value_compare()) is greater than the second one. - - - - - Checks if the given #GValue contains a #GST_TYPE_ARRAY value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_BITMASK value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_BUFFER value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_CAPS value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_CAPS_FEATURES value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_DATE_TIME value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_DOUBLE_RANGE value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_FLAG_SET value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_FRACTION value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_FRACTION_RANGE value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_INT64_RANGE value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_INT_RANGE value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_LIST value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_SAMPLE value. - - - - the #GValue to check - - - - - Checks if the given #GValue contains a #GST_TYPE_STRUCTURE value. - - - - the #GValue to check - - - - - Indicates that the first value provided to a comparison function -(gst_value_compare()) is lesser than the second one. - - - - - Indicates that the comparison function (gst_value_compare()) can not -determine a order for the two provided values. - - - - - The major version of GStreamer at compile time: - - - - - The micro version of GStreamer at compile time: - - - - - The minor version of GStreamer at compile time: - - - - - The nano version of GStreamer at compile time: -Actual releases have 0, GIT versions have 1, prerelease versions have 2-... - - - - - A fundamental type that describes an ordered list of #GValue - - Appends @append_value to the GstValueArray in @value. - - - - - - - a #GValue of type #GST_TYPE_ARRAY - - - - the value to append - - - - - - Appends @append_value to the GstValueArray in @value. - - - - - - - a #GValue of type #GST_TYPE_ARRAY - - - - the value to append - - - - - - Gets the number of values contained in @value. - - - the number of values - - - - - a #GValue of type #GST_TYPE_ARRAY - - - - - - Gets the value that is a member of the array contained in @value and -has the index @index. - - - the value at the given index - - - - - a #GValue of type #GST_TYPE_ARRAY - - - - index of value to get from the array - - - - - - Initializes and pre-allocates a #GValue of type #GST_VALUE_ARRAY. - - - The #GValue structure that has been passed in - - - - - A zero-filled (uninitialized) #GValue structure - - - - The number of entries to pre-allocate in the array - - - - - - Prepends @prepend_value to the GstValueArray in @value. - - - - - - - a #GValue of type #GST_TYPE_ARRAY - - - - the value to prepend - - - - - - - Used together with gst_value_compare() to compare #GValue items. - - - one of GST_VALUE_LESS_THAN, GST_VALUE_EQUAL, GST_VALUE_GREATER_THAN -or GST_VALUE_UNORDERED - - - - - first value for comparison - - - - second value for comparison - - - - - - Used by gst_value_deserialize() to parse a non-binary form into the #GValue. - - - %TRUE for success - - - - - a #GValue - - - - a string - - - - - - A fundamental type that describes an unordered list of #GValue - - Appends @append_value to the GstValueList in @value. - - - - - - - a #GValue of type #GST_TYPE_LIST - - - - the value to append - - - - - - Appends @append_value to the GstValueList in @value. - - - - - - - a #GValue of type #GST_TYPE_LIST - - - - the value to append - - - - - - Concatenates copies of @value1 and @value2 into a list. Values that are not -of type #GST_TYPE_LIST are treated as if they were lists of length 1. -@dest will be initialized to the type #GST_TYPE_LIST. - - - - - - - an uninitialized #GValue to take the result - - - - a #GValue - - - - a #GValue - - - - - - Gets the number of values contained in @value. - - - the number of values - - - - - a #GValue of type #GST_TYPE_LIST - - - - - - Gets the value that is a member of the list contained in @value and -has the index @index. - - - the value at the given index - - - - - a #GValue of type #GST_TYPE_LIST - - - - index of value to get from the list - - - - - - Initializes and pre-allocates a #GValue of type #GST_VALUE_LIST. - - - The #GValue structure that has been passed in - - - - - A zero-filled (uninitialized) #GValue structure - - - - The number of entries to pre-allocate in the list - - - - - - Merges copies of @value1 and @value2. Values that are not -of type #GST_TYPE_LIST are treated as if they were lists of length 1. - -The result will be put into @dest and will either be a list that will not -contain any duplicates, or a non-list type (if @value1 and @value2 -were equal). - - - - - - - an uninitialized #GValue to take the result - - - - a #GValue - - - - a #GValue - - - - - - Prepends @prepend_value to the GstValueList in @value. - - - - - - - a #GValue of type #GST_TYPE_LIST - - - - the value to prepend - - - - - - - Used by gst_value_serialize() to obtain a non-binary form of the #GValue. - -Free-function: g_free - - - the string representation of the value - - - - - a #GValue - - - - - - VTable for the #GValue @type. - - - a #GType - - - - a #GstValueCompareFunc - - - - a #GstValueSerializeFunc - - - - a #GstValueDeserializeFunc - - - - - - - - - - Store a 16 bit unsigned integer value in big endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 16 bit unsigned integer value in little endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 24 bit unsigned integer value in big endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 24 bit unsigned integer value in little endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 32 bit unsigned integer value in big endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 32 bit unsigned integer value in little endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 64 bit unsigned integer value in big endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store a 64 bit unsigned integer value in little endian format into the memory buffer. - - - - memory location - - - value to store - - - - - Store an 8 bit unsigned integer value into the memory buffer. - - - - memory location - - - value to store - - - - - Get the maximum amount of memory blocks that a buffer can hold. This is a -compile time constant that can be queried with the function. - -When more memory blocks are added, existing memory blocks will be merged -together to make room for the new block. - - - the maximum amount of memory blocks that a buffer can hold. - - - - - Find and return a #GstParentBufferMeta if one exists on the -buffer - - - - a #GstBuffer - - - - - - - - - - - - Tests if you can safely write to a buffer's metadata or its memory array. -It is only safe to change buffer metadata when the current reference is -writable, i.e. nobody can see the modifications you will make. - - - - a #GstBuffer - - - - - Append @b at the end of @l. - - - - a #GstBufferList - - - a #GstBuffer - - - - - Tests if you can safely add buffers and groups into a buffer list. - - - - a #GstBufferList - - - - - Makes a writable buffer list from the given buffer list. If the source buffer -list is already writable, this will simply return the same buffer list. A -copy will otherwise be made using gst_buffer_list_copy(). - - - - a #GstBufferList - - - - - Returns a writable copy of @buf. If the source buffer is -already writable, this will simply return the same buffer. - -Use this function to ensure that a buffer can be safely modified before -making changes to it, including changing the metadata such as PTS/DTS. - -If the reference count of the source buffer @buf is exactly one, the caller -is the sole owner and this function will return the buffer object unchanged. - -If there is more than one reference on the object, a copy will be made using -gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the -caller will now own a reference to the new returned buffer object. Note -that this just copies the buffer structure itself, the underlying memory is -not copied if it can be shared amongst multiple buffers. - -In short, this function unrefs the buf in the argument and refs the buffer -that it returns. Don't access the argument after calling this function unless -you have an additional reference to it. - - - - a #GstBuffer - - - - - - - - - - - - Modifies a pointer to a #GstBuffer to point to a different #GstBuffer. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -buffer is unreffed, the new is reffed). - -Either @nbuf or the #GstBuffer pointed to by @obuf may be %NULL. - - - %TRUE when @obuf was different from @nbuf. - - - - - pointer to a pointer to - a #GstBuffer to be replaced. - - - - pointer to a #GstBuffer that will - replace the buffer pointed to by @obuf. - - - - - - Calculates the linear regression of the values @xy and places the -result in @m_num, @m_denom, @b and @xbase, representing the function - y(x) = m_num/m_denom * (x - xbase) + b -that has the least-square distance from all points @x and @y. - -@r_squared will contain the remaining error. - -If @temp is not %NULL, it will be used as temporary space for the function, -in which case the function works without any allocation at all. If @temp is -%NULL, an allocation will take place. @temp should have at least the same -amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). - -> This function assumes (x,y) values with reasonable large differences -> between them. It will not calculate the exact results if the differences -> between neighbouring values are too small due to not being able to -> represent sub-integer values during the calculations. - - - %TRUE if the linear regression was successfully calculated - - - - - Pairs of (x,y) values - - - - Temporary scratch space used by the function - - - - number of (x,y) pairs - - - - numerator of calculated slope - - - - denominator of calculated slope - - - - Offset at Y-axis - - - - Offset at X-axis - - - - R-squared - - - - - - Creates a #GstCapsFeatures from a string representation. - -Free-function: gst_caps_features_free - - - a new #GstCapsFeatures or - %NULL when the string could not be parsed. Free with - gst_caps_features_free() after use. - - - - - a string representation of a #GstCapsFeatures. - - - - - - Converts @caps from a string representation. - -The current implementation of serialization will lead to unexpected results -when there are nested #GstCaps / #GstStructure deeper than one level. - - - a newly allocated #GstCaps - - - - - a string to convert to #GstCaps - - - - - - Tests if you can safely modify @caps. It is only safe to modify caps when -there is only one owner of the caps - ie, the object is writable. - - - - a #GstCaps - - - - - Returns a writable copy of @caps. - -If there is only one reference count on @caps, the caller must be the owner, -and so this function will return the caps object unchanged. If on the other -hand there is more than one reference on the object, a new caps object will -be returned. The caller's reference on @caps will be removed, and instead the -caller will own a reference to the returned object. - -In short, this function unrefs the caps in the argument and refs the caps -that it returns. Don't access the argument after calling this function. See -also: gst_caps_ref(). - - - - a #GstCaps - - - - - Modifies a pointer to a #GstCaps to point to a different #GstCaps. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -caps is unreffed, the new is reffed). - -Either @new_caps or the #GstCaps pointed to by @old_caps may be %NULL. - - - %TRUE if @new_caps was different from @old_caps - - - - - pointer to a pointer - to a #GstCaps to be replaced. - - - - pointer to a #GstCaps that will - replace the caps pointed to by @old_caps. - - - - - - Modifies a pointer to a #GstCaps to point to a different #GstCaps. This -function is similar to gst_caps_replace() except that it takes ownership -of @new_caps. - - - %TRUE if @new_caps was different from @old_caps - - - - - pointer to a pointer to a #GstCaps to be - replaced. - - - - pointer to a #GstCaps that will - replace the caps pointed to by @old_caps. - - - - - - Clears a reference to a #GstMiniObject. - -@object_ptr must not be %NULL. - -If the reference is %NULL then this function does nothing. -Otherwise, the reference count of the object is decreased using -gst_mini_object_unref() and the pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - a pointer to a #GstMiniObject reference - - - - - - Clears a reference to a #GstObject. - -@object_ptr must not be %NULL. - -If the reference is %NULL then this function does nothing. -Otherwise, the reference count of the object is decreased using -gst_object_unref() and the pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - a pointer to a #GstObject reference - - - - - - Clears a reference to a #GstStructure. - -@structure_ptr must not be %NULL. - -If the reference is %NULL then this function does nothing. -Otherwise, the structure is free'd using gst_structure_free() and the -pointer is set to %NULL. - -A macro is also included that allows this function to be used without -pointer casts. - - - - - - - a pointer to a #GstStructure reference - - - - - - Tests if you can safely write into a context's structure or validly -modify the seqnum and timestamp fields. - - - - a #GstContext - - - - - Checks if a context is writable. If not, a writable copy is made and -returned. - - - - the context to make writable - - - - - - - - - - - Adds the logging function to the list of logging functions. -Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. - - - - - - - the function to use - - - - user data - - - - called when @user_data is not used anymore - - - - - - Adds a memory ringbuffer based debug logger that stores up to -@max_size_per_thread bytes of logs per thread and times out threads after -@thread_timeout seconds of inactivity. - -Logs can be fetched with gst_debug_ring_buffer_logger_get_logs() and the -logger can be removed again with gst_debug_remove_ring_buffer_logger(). -Only one logger at a time is possible. - - - - - - - Maximum size of log per thread in bytes - - - - Timeout for threads in seconds - - - - - - To aid debugging applications one can use this method to obtain the whole -network of gstreamer elements that form the pipeline into an dot file. -This data can be processed with graphviz to get an image. - - - a string containing the pipeline in graphviz -dot format. - - - - - the top-level pipeline that should be analyzed - - - - type of #GstDebugGraphDetails to use - - - - - - To aid debugging applications one can use this method to write out the whole -network of gstreamer elements that form the pipeline into an dot file. -This file can be processed with graphviz to get an image. - -``` shell - dot -Tpng -oimage.png graph_lowlevel.dot -``` - - - - - - - the top-level pipeline that should be analyzed - - - - type of #GstDebugGraphDetails to use - - - - output base filename (e.g. "myplayer") - - - - - - This works like gst_debug_bin_to_dot_file(), but adds the current timestamp -to the filename, so that it can be used to take multiple snapshots. - - - - - - - the top-level pipeline that should be analyzed - - - - type of #GstDebugGraphDetails to use - - - - output base filename (e.g. "myplayer") - - - - - - Constructs a string that can be used for getting the desired color in color -terminals. -You need to free the string after use. - - - a string containing the color - definition - - - - - the color info - - - - - - Constructs an integer that can be used for getting the desired color in -windows' terminals (cmd.exe). As there is no mean to underline, we simply -ignore this attribute. - -This function returns 0 on non-windows machines. - - - an integer containing the color definition - - - - - the color info - - - - - - Returns a snapshot of a all categories that are currently in use . This list -may change anytime. -The caller has to free the list after use. - - - the list of - debug categories - - - - - - - Changes the coloring mode for debug output. - - - see @GstDebugColorMode for possible values. - - - - - Returns the default threshold that is used for new categories. - - - the default threshold level - - - - - - - a stack trace, if libunwind or glibc backtrace are -present, else %NULL. - - - - - A set of #GstStackTraceFlags to determine how the stack trace should -look like. Pass #GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace. - - - - - - Checks if debugging output is activated. - - - %TRUE, if debugging is activated - - - - - Checks if the debugging output should be colored. - - - %TRUE, if the debug output should be colored. - - - - - Get the string representation of a debugging level - - - the name - - - - - the level to get the name for - - - - - - Logs the given message using the currently registered debugging handlers. - - - - - - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the object this message relates to, - or %NULL if none - - - - a printf style format string - - - - optional arguments for the format - - - - - - The default logging handler used by GStreamer. Logging functions get called -whenever a macro like GST_DEBUG or similar is used. By default this function -is setup to output the message and additional info to stderr (or the log file -specified via the GST_DEBUG_FILE environment variable) as received via -@user_data. - -You can add other handlers by using gst_debug_add_log_function(). -And you can remove this handler by calling -gst_debug_remove_log_function(gst_debug_log_default); - - - - - - - category to log - - - - level of the message - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the object this message relates to, - or %NULL if none - - - - the actual message - - - - the FILE* to log to - - - - - - Returns the string representation for the specified debug log message -formatted in the same way as gst_debug_log_default() (the default handler), -without color. The purpose is to make it easy for custom log output -handlers to get a log output that is identical to what the default handler -would write out. - - - - - - - category to log - - - - level of the message - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the object this message relates to, - or %NULL if none - - - - the actual message - - - - - - Logs the given message using the currently registered debugging handlers. - - - - - - - category to log - - - - level of the message is in - - - - the file that emitted the message, usually the __FILE__ identifier - - - - the function that emitted the message - - - - the line from that the message was emitted, usually __LINE__ - - - - the object this message relates to, - or %NULL if none - - - - a printf style format string - - - - optional arguments for the format - - - - - - If libunwind, glibc backtrace or DbgHelp are present -a stack trace is printed. - - - - - - - Removes all registered instances of the given logging functions. - - - How many instances of the function were removed - - - - - the log function to remove, or %NULL to - remove the default log function - - - - - - Removes all registered instances of log functions with the given user data. - - - How many instances of the function were removed - - - - - user data of the log function to remove - - - - - - Removes any previously added ring buffer logger with -gst_debug_add_ring_buffer_logger(). - - - - - - - Fetches the current logs per thread from the ring buffer logger. See -gst_debug_add_ring_buffer_logger() for details. - - - NULL-terminated array of -strings with the debug output per thread - - - - - - - If activated, debugging messages are sent to the debugging -handlers. -It makes sense to deactivate it for speed issues. -> This function is not threadsafe. It makes sense to only call it -during initialization. - - - - - - - Whether to use debugging output or not - - - - - - Changes the coloring mode for debug output. - -This function may be called before gst_init(). - - - - - - - The coloring mode for debug output. See @GstDebugColorMode. - - - - - - Changes the coloring mode for debug output. - -This function may be called before gst_init(). - - - - - - - The coloring mode for debug output. One of the following: -"on", "auto", "off", "disable", "unix". - - - - - - Sets or unsets the use of coloured debugging output. -Same as gst_debug_set_color_mode () with the argument being -being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF. - -This function may be called before gst_init(). - - - - - - - Whether to use colored output or not - - - - - - Sets the default threshold to the given level and updates all categories to -use this threshold. - -This function may be called before gst_init(). - - - - - - - level to set - - - - - - Sets all categories which match the given glob style pattern to the given -level. - - - - - - - name of the categories to set - - - - level to set them to - - - - - - Sets the debug logging wanted in the same form as with the GST_DEBUG -environment variable. You can use wildcards such as '*', but note that -the order matters when you use wild cards, e.g. "foosrc:6,*src:3,*:2" sets -everything to log level 2. - - - - - - - comma-separated list of "category:level" pairs to be used - as debug logging levels - - - - %TRUE to clear all previously-set debug levels before setting - new thresholds -%FALSE if adding the threshold described by @list to the one already set. - - - - - - Resets all categories with the given name back to the default level. - - - - - - - name of the categories to set - - - - - - Clean up any resources created by GStreamer in gst_init(). - -It is normally not needed to call this function in a normal application -as the resources will automatically be freed when the program terminates. -This function is therefore mostly used by testsuites and other memory -profiling tools. - -After this call GStreamer (including this method) should not be used anymore. - - - - - - - Registers a new #GstDynamicTypeFactory in the registry - - - - - - - The #GstPlugin to register @dyn_type for - - - - The #GType to register dynamically - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Returns a copy of the name of @elem. -Caller should g_free() the return value after usage. -For a nameless element, this returns %NULL, which you can safely g_free() -as well. - - - - a #GstElement to get the name of @elem. - - - - - Get the parent of an element. - - - - a #GstElement to get the parent of. - - - - - Sets the name of the element, getting rid of the old name if there was one. - - - - a #GstElement to set the name of. - - - the new name - - - - - Sets the parent of an element. - - - - a #GstElement to set the parent of. - - - the new parent #GstObject of the element. - - - - - Get a string describing the error message in the current locale. - - - a newly allocated string describing - the error message (in UTF-8 encoding) - - - - - the GStreamer error domain this error belongs to. - - - - the error code belonging to the domain. - - - - - - Tests if you can safely write data into a event's structure or validly -modify the seqnum and timestamp field. - - - - a #GstEvent - - - - - Makes a writable event from the given event. If the source event is -already writable, this will simply return the same event. A copy will -otherwise be made using gst_event_copy(). - - - - a #GstEvent - - - - - Modifies a pointer to a #GstEvent to point to a different #GstEvent. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -event is unreffed, the new one is reffed). - -Either @new_event or the #GstEvent pointed to by @old_event may be %NULL. - - - %TRUE if @new_event was different from @old_event - - - - - pointer to a - pointer to a #GstEvent to be replaced. - - - - pointer to a #GstEvent that will - replace the event pointed to by @old_event. - - - - - - Atomically replace the #GstEvent pointed to by @old_event with %NULL and -return the original event. - - - the #GstEvent that was in @old_event - - - - - pointer to a - pointer to a #GstEvent to be stolen. - - - - - - Modifies a pointer to a #GstEvent to point to a different #GstEvent. This -function is similar to gst_event_replace() except that it takes ownership of -@new_event. - -Either @new_event or the #GstEvent pointed to by @old_event may be %NULL. - - - %TRUE if @new_event was different from @old_event - - - - - pointer to a - pointer to a #GstEvent to be stolen. - - - - pointer to a #GstEvent that will - replace the event pointed to by @old_event. - - - - - - Gets the #GstEventTypeFlags associated with @type. - - - a #GstEventTypeFlags. - - - - - a #GstEventType - - - - - - Get a printable name for the given event type. Do not modify or free. - - - a reference to the static name of the event. - - - - - the event type - - - - - - Get the unique quark for the given event type. - - - the quark associated with the event type - - - - - the event type - - - - - - Similar to g_filename_to_uri(), but attempts to handle relative file paths -as well. Before converting @filename into an URI, it will be prefixed by -the current working directory if it is a relative path, and then the path -will be canonicalised so that it doesn't contain any './' or '../' segments. - -On Windows @filename should be in UTF-8 encoding. - - - newly-allocated URI string, or NULL on error. The caller must - free the URI string with g_free() when no longer needed. - - - - - absolute or relative file name path - - - - - - Gets a string representing the given flow return. - - - a static string with the name of the flow return. - - - - - a #GstFlowReturn to get the name of. - - - - - - Get the unique quark for the given GstFlowReturn. - - - the quark associated with the flow return or 0 if an -invalid return was specified. - - - - - a #GstFlowReturn to get the quark of. - - - - - - Return the format registered with the given nick. - - - The format with @nick or GST_FORMAT_UNDEFINED -if the format was not registered. - - - - - The nick of the format - - - - - - Get details about the given format. - - - The #GstFormatDefinition for @format or %NULL -on failure. - -MT safe. - - - - - The format to get details of - - - - - - Get a printable name for the given format. Do not modify or free. - - - a reference to the static name of the format -or %NULL if the format is unknown. - - - - - a #GstFormat - - - - - - Iterate all the registered formats. The format definition is read -only. - - - a GstIterator of #GstFormatDefinition. - - - - - Create a new GstFormat based on the nick or return an -already registered format with that nick. - - - A new GstFormat or an already registered format -with the same nick. - -MT safe. - - - - - The nick of the new format - - - - The description of the new format - - - - - - Get the unique quark for the given format. - - - the quark associated with the format or 0 if the format -is unknown. - - - - - a #GstFormat - - - - - - See if the given format is inside the format array. - - - %TRUE if the format is found inside the array - - - - - The format array to search - - - - - - the format to find - - - - - - Convert @value to a guint64. - - - - the #gdouble value to convert - - - - - This helper is mostly helpful for plugins that need to -inspect the folder of the main executable to determine -their set of features. - -When a plugin is initialized from the gst-plugin-scanner -external process, the returned path will be the same as from the -parent process. - - - The path of the executable that - initialized GStreamer, or %NULL if it could not be determined. - - - - - Convert @value to a gdouble. - - - - the #guint64 value to convert - - - - - Allocates, fills and returns a 0-terminated string from the printf style -@format string and corresponding arguments. - -See gst_info_vasprintf() for when this function is required. - -Free with g_free(). - - - a newly allocated null terminated string or %NULL on any error - - - - - a printf style format string - - - - the printf arguments for @format - - - - - - Allocates, fills and returns a null terminated string from the printf style -@format string and @args. - -See gst_info_vasprintf() for when this function is required. - -Free with g_free(). - - - a newly allocated null terminated string or %NULL on any error - - - - - a printf style format string - - - - the va_list of printf arguments for @format - - - - - - Allocates and fills a string large enough (including the terminating null -byte) to hold the specified printf style @format and @args. - -This function deals with the GStreamer specific printf specifiers -#GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. If you do not have these specifiers -in your @format string, you do not need to use this function and can use -alternatives such as g_vasprintf(). - -Free @result with g_free(). - - - the length of the string allocated into @result or -1 on any error - - - - - the resulting string - - - - a printf style format string - - - - the va_list of printf arguments for @format - - - - - - Initializes the GStreamer library, setting up internal path lists, -registering built-in elements, and loading standard plugins. - -Unless the plugin registry is disabled at compile time, the registry will be -loaded. By default this will also check if the registry cache needs to be -updated and rescan all plugins if needed. See gst_update_registry() for -details and section -<link linkend="gst-running">Running GStreamer Applications</link> -for how to disable automatic registry updates. - -> This function will terminate your program if it was unable to initialize -> GStreamer for some reason. If you want your program to fall back, -> use gst_init_check() instead. - -WARNING: This function does not work in the same way as corresponding -functions in other glib-style libraries, such as gtk_init\(\). In -particular, unknown command line options cause this function to -abort program execution. - - - - - - - pointer to application's argc - - - - pointer to application's argv - - - - - - - - Initializes the GStreamer library, setting up internal path lists, -registering built-in elements, and loading standard plugins. - -This function will return %FALSE if GStreamer could not be initialized -for some reason. If you want your program to fail fatally, -use gst_init() instead. - - - %TRUE if GStreamer could be initialized. - - - - - pointer to application's argc - - - - pointer to application's argv - - - - - - - - Returns a #GOptionGroup with GStreamer's argument specifications. The -group is set up to use standard GOption callbacks, so when using this -group in combination with GOption parsing methods, all argument parsing -and initialization is automated. - -This function is useful if you want to integrate GStreamer with other -libraries that use GOption (see g_option_context_add_group() ). - -If you use this function, you should make sure you initialise the GLib -threading system as one of the very first things in your program -(see the example at the beginning of this section). - - - a pointer to GStreamer's option group. - - - - - Checks if @obj is a #GstCapsFeatures - - - %TRUE if @obj is a #GstCapsFeatures %FALSE otherwise - - - - - - - - - - Use this function to check if GStreamer has been initialized with gst_init() -or gst_init_check(). - - - %TRUE if initialization has been done, %FALSE otherwise. - - - - - - - - - - - Create a #GstStructure to be used with #gst_element_message_full_with_details - - - - - - - Name of the first field to set - - - - variable arguments in the same form as #GstStructure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Tests if you can safely write into a message's structure or validly -modify the seqnum and timestamp fields. - - - - a #GstMessage - - - - - Checks if a message is writable. If not, a writable copy is made and -returned. - - - - the message to make writable - - - - - - - - - - - - - - - - - - - - - - - - - - - Modifies a pointer to a #GstMessage to point to a different #GstMessage. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -message is unreffed, the new one is reffed). - -Either @new_message or the #GstMessage pointed to by @old_message may be %NULL. - - - %TRUE if @new_message was different from @old_message - - - - - pointer to a - pointer to a #GstMessage to be replaced. - - - - pointer to a #GstMessage that will - replace the message pointed to by @old_message. - - - - - - Get a printable name for the given message type. Do not modify or free. - - - a reference to the static name of the message. - - - - - the message type - - - - - - Get the unique quark for the given message type. - - - the quark associated with the message type - - - - - the message type - - - - - - - - an array of tags as strings. - - - - - - - an API - - - - - - Check if @api was registered with @tag. - - - %TRUE if @api was registered with @tag. - - - - - an API - - - - the tag to check - - - - - - Register and return a GType for the @api and associate it with -@tags. - - - a unique GType for @api. - - - - - an API to register - - - - tags for @api - - - - - - - - Lookup a previously registered meta info structure by its implementation name -@impl. - - - a #GstMetaInfo with @impl, or -%NULL when no such metainfo exists. - - - - - the name - - - - - - Register a new #GstMeta implementation. - -The same @info can be retrieved later with gst_meta_get_info() by using -@impl as the key. - - - a #GstMetaInfo that can be used to -access metadata. - - - - - the type of the #GstMeta API - - - - the name of the #GstMeta implementation - - - - the size of the #GstMeta structure - - - - a #GstMetaInitFunction - - - - a #GstMetaFreeFunction - - - - a #GstMetaTransformFunction - - - - - - Atomically modifies a pointer to point to a new mini-object. -The reference count of @olddata is decreased and the reference count of -@newdata is increased. - -Either @newdata and the value pointed to by @olddata may be %NULL. - - - %TRUE if @newdata was different from @olddata - - - - - pointer to a pointer to a - mini-object to be replaced - - - - pointer to new mini-object - - - - - - Replace the current #GstMiniObject pointer to by @olddata with %NULL and -return the old value. - - - the #GstMiniObject at @oldata - - - - - pointer to a pointer to a mini-object to - be stolen - - - - - - Modifies a pointer to point to a new mini-object. The modification -is done atomically. This version is similar to gst_mini_object_replace() -except that it does not increase the refcount of @newdata and thus -takes ownership of @newdata. - -Either @newdata and the value pointed to by @olddata may be %NULL. - - - %TRUE if @newdata was different from @olddata - - - - - pointer to a pointer to a mini-object to - be replaced - - - - pointer to new mini-object - - - - - - - - - - - - - Get a copy of the name of the pad. g_free() after usage. - -MT safe. - - - - the pad to get the name from - - - - - Get the parent of @pad. This function increases the refcount -of the parent object so you should gst_object_unref() it after usage. -Can return %NULL if the pad did not have a parent. - -MT safe. - - - - the pad to get the parent of - - - - - Return the name of a pad mode, for use in debug messages mostly. - - - short mnemonic for pad mode @mode - - - - - the pad mode - - - - - - - - - - - - - Calls gst_pad_set_activate_function_full() with %NULL for the user_data and -notify. - - - - a #GstPad. - - - the #GstPadActivateFunction to set. - - - - - Calls gst_pad_set_activatemode_function_full() with %NULL for the user_data and -notify. - - - - a #GstPad. - - - the #GstPadActivateModeFunction to set. - - - - - Calls gst_pad_set_chain_function_full() with %NULL for the user_data and -notify. - - - - a sink #GstPad. - - - the #GstPadChainFunction to set. - - - - - Calls gst_pad_set_chain_list_function_full() with %NULL for the user_data and -notify. - - - - a sink #GstPad. - - - the #GstPadChainListFunction to set. - - - - - Calls gst_pad_set_event_full_function_full() with %NULL for the user_data and -notify. - - - - a #GstPad of either direction. - - - the #GstPadEventFullFunction to set. - - - - - Calls gst_pad_set_event_function_full() with %NULL for the user_data and -notify. - - - - a #GstPad of either direction. - - - the #GstPadEventFunction to set. - - - - - Calls gst_pad_set_getrange_function_full() with %NULL for the user_data and -notify. - - - - a source #GstPad. - - - the #GstPadGetRangeFunction to set. - - - - - Calls gst_pad_set_iterate_internal_links_function_full() with %NULL -for the user_data and notify. - - - - a #GstPad of either direction. - - - the #GstPadIterIntLinkFunction to set. - - - - - Calls gst_pad_set_link_function_full() with %NULL -for the user_data and notify. - - - - a #GstPad. - - - the #GstPadLinkFunction to set. - - - - - Calls gst_pad_set_query_function_full() with %NULL for the user_data and -notify. - - - - a #GstPad of either direction. - - - the #GstPadQueryFunction to set. - - - - - Calls gst_pad_set_unlink_function_full() with %NULL -for the user_data and notify. - - - - a #GstPad. - - - the #GstPadUnlinkFunction to set. - - - - - This function creates a GstArray GParamSpec for use by objects/elements -that want to expose properties of GstArray type. This function is -typically * used in connection with g_object_class_install_property() in a -GObjects's instance_init function. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - GParamSpec of the array - - - - flags for the property specified - - - - - - This function creates a fraction GParamSpec for use by objects/elements -that want to expose properties of fraction type. This function is typically -used in connection with g_object_class_install_property() in a GObjects's -instance_init function. - - - a newly created parameter specification - - - - - canonical name of the property specified - - - - nick name for the property specified - - - - description of the property specified - - - - minimum value (fraction numerator) - - - - minimum value (fraction denominator) - - - - maximum value (fraction numerator) - - - - maximum value (fraction denominator) - - - - default value (fraction numerator) - - - - default value (fraction denominator) - - - - flags for the property specified - - - - - - - - - - - - - Get the global #GstMetaInfo describing the #GstParentBufferMeta meta. - - - The #GstMetaInfo - - - - - This is a convenience wrapper around gst_parse_launch() to create a -#GstBin from a gst-launch-style pipeline description. See -gst_parse_launch() and the gst-launch man page for details about the -syntax. Ghost pads on the bin for unlinked source or sink pads -within the bin can automatically be created (but only a maximum of -one ghost pad for each direction will be created; if you expect -multiple unlinked source pads or multiple unlinked sink pads -and want them all ghosted, you will have to create the ghost pads -yourself). - - - a - newly-created bin, or %NULL if an error occurred. - - - - - command line describing the bin - - - - whether to automatically create ghost pads - for unlinked source or sink pads within the bin - - - - - - This is a convenience wrapper around gst_parse_launch() to create a -#GstBin from a gst-launch-style pipeline description. See -gst_parse_launch() and the gst-launch man page for details about the -syntax. Ghost pads on the bin for unlinked source or sink pads -within the bin can automatically be created (but only a maximum of -one ghost pad for each direction will be created; if you expect -multiple unlinked source pads or multiple unlinked sink pads -and want them all ghosted, you will have to create the ghost pads -yourself). - - - a newly-created - element, which is guaranteed to be a bin unless - #GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or %NULL if an error - occurred. - - - - - command line describing the bin - - - - whether to automatically create ghost pads - for unlinked source or sink pads within the bin - - - - a parse context allocated with - gst_parse_context_new(), or %NULL - - - - parsing options, or #GST_PARSE_FLAG_NONE - - - - - - Get the error quark used by the parsing subsystem. - - the quark of the parse errors. - - - - - Create a new pipeline based on command line syntax. -Please note that you might get a return value that is not %NULL even though -the @error is set. In this case there was a recoverable parsing error and you -can try to play the pipeline. - -To create a sub-pipeline (bin) for embedding into an existing pipeline -use gst_parse_bin_from_description(). - - - a new element on success, %NULL on - failure. If more than one toplevel element is specified by the - @pipeline_description, all elements are put into a #GstPipeline, which - than is returned. - - - - - the command line describing the pipeline - - - - - - Create a new pipeline based on command line syntax. -Please note that you might get a return value that is not %NULL even though -the @error is set. In this case there was a recoverable parsing error and you -can try to play the pipeline. - -To create a sub-pipeline (bin) for embedding into an existing pipeline -use gst_parse_bin_from_description_full(). - - - a new element on success, %NULL on - failure. If more than one toplevel element is specified by the - @pipeline_description, all elements are put into a #GstPipeline, which - then is returned (unless the GST_PARSE_FLAG_PLACE_IN_BIN flag is set, in - which case they are put in a #GstBin instead). - - - - - the command line describing the pipeline - - - - a parse context allocated with - gst_parse_context_new(), or %NULL - - - - parsing options, or #GST_PARSE_FLAG_NONE - - - - - - Create a new element based on command line syntax. -@error will contain an error message if an erroneous pipeline is specified. -An error does not mean that the pipeline could not be constructed. - - - a new element on success and %NULL -on failure. - - - - - null-terminated array of arguments - - - - - - - - Create a new element based on command line syntax. -@error will contain an error message if an erroneous pipeline is specified. -An error does not mean that the pipeline could not be constructed. - - - a new element on success; on - failure, either %NULL or a partially-constructed bin or element will be - returned and @error will be set (unless you passed - #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then %NULL will always be returned - on failure) - - - - - null-terminated array of arguments - - - - - - a parse context allocated with - gst_parse_context_new(), or %NULL - - - - parsing options, or #GST_PARSE_FLAG_NONE - - - - - - Get the error quark. - - The error quark used in GError messages - - - - - Returns the name of @feature. -For a nameless plugin feature, this returns %NULL. - - - - a #GstPluginFeature to get the name of @feature. - - - - - Sets the name of the plugin feature, getting rid of the old name if there was one. - - - - a #GstPluginFeature to set the name of. - - - the new name - - - - - Create a new file descriptor set. If @controllable, it -is possible to restart or flush a call to gst_poll_wait() with -gst_poll_restart() and gst_poll_set_flushing() respectively. - -Free-function: gst_poll_free - - - a new #GstPoll, or %NULL in - case of an error. Free with gst_poll_free(). - - - - - whether it should be possible to control a wait. - - - - - - Create a new poll object that can be used for scheduling cancellable -timeouts. - -A timeout is performed with gst_poll_wait(). Multiple timeouts can be -performed from different threads. - -Free-function: gst_poll_free - - - a new #GstPoll, or %NULL in - case of an error. Free with gst_poll_free(). - - - - - Gets the directory for application specific presets if set by the -application. - - - the directory or %NULL, don't free or modify -the string - - - - - Sets an extra directory as an absolute path that should be considered when -looking for presets. Any presets in the application dir will shadow the -system presets. - - - %TRUE for success, %FALSE if the dir already has been set - - - - - the application specific preset dir - - - - - - Outputs a formatted message via the GLib print handler. The default print -handler simply outputs the message to stdout. - -This function will not append a new-line character at the end, unlike -gst_println() which will. - -All strings must be in ASCII or UTF-8 encoding. - -This function differs from g_print() in that it supports all the additional -printf specifiers that are supported by GStreamer's debug logging system, -such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. - -This function is primarily for printing debug output. - - - - - - - a printf style format string - - - - the printf arguments for @format - - - - - - Outputs a formatted message via the GLib error message handler. The default -handler simply outputs the message to stderr. - -This function will not append a new-line character at the end, unlike -gst_printerrln() which will. - -All strings must be in ASCII or UTF-8 encoding. - -This function differs from g_printerr() in that it supports the additional -printf specifiers that are supported by GStreamer's debug logging system, -such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. - -This function is primarily for printing debug output. - - - - - - - a printf style format string - - - - the printf arguments for @format - - - - - - Outputs a formatted message via the GLib error message handler. The default -handler simply outputs the message to stderr. - -This function will append a new-line character at the end, unlike -gst_printerr() which will not. - -All strings must be in ASCII or UTF-8 encoding. - -This function differs from g_printerr() in that it supports the additional -printf specifiers that are supported by GStreamer's debug logging system, -such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. - -This function is primarily for printing debug output. - - - - - - - a printf style format string - - - - the printf arguments for @format - - - - - - Outputs a formatted message via the GLib print handler. The default print -handler simply outputs the message to stdout. - -This function will append a new-line character at the end, unlike -gst_print() which will not. - -All strings must be in ASCII or UTF-8 encoding. - -This function differs from g_print() in that it supports all the additional -printf specifiers that are supported by GStreamer's debug logging system, -such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. - -This function is primarily for printing debug output. - - - - - - - a printf style format string - - - - the printf arguments for @format - - - - - - Iterates the supplied list of UUIDs and checks the GstRegistry for -all the decryptors supporting one of the supplied UUIDs. - - - -A null terminated array containing all -the @system_identifiers supported by the set of available decryptors, or -%NULL if no matches were found. - - - - - - - -A null terminated array of strings that contains the UUID values of each -protection system that is to be checked. - - - - - - - - - - - - - - - - - - - - - Iterates the supplied list of UUIDs and checks the GstRegistry for -an element that supports one of the supplied UUIDs. If more than one -element matches, the system ID of the highest ranked element is selected. - - - One of the strings from -@system_identifiers that indicates the highest ranked element that -implements the protection system indicated by that system ID, or %NULL if no -element has been found. - - - - - A null terminated array of strings -that contains the UUID values of each protection system that is to be -checked. - - - - - - - - Tests if you can safely write data into a query's structure. - - - - a #GstQuery - - - - - Makes a writable query from the given query. - - - - a #GstQuery to make writable - - - - - Modifies a pointer to a #GstQuery to point to a different #GstQuery. The -modification is done atomically (so this is useful for ensuring thread safety -in some cases), and the reference counts are updated appropriately (the old -query is unreffed, the new one is reffed). - -Either @new_query or the #GstQuery pointed to by @old_query may be %NULL. - - - %TRUE if @new_query was different from @old_query - - - - - pointer to a pointer to a - #GstQuery to be replaced. - - - - pointer to a #GstQuery that will - replace the query pointed to by @old_query. - - - - - - Gets the #GstQueryTypeFlags associated with @type. - - - a #GstQueryTypeFlags. - - - - - a #GstQueryType - - - - - - Get a printable name for the given query type. Do not modify or free. - - - a reference to the static name of the query. - - - - - the query type - - - - - - Get the unique quark for the given query type. - - - the quark associated with the query type - - - - - the query type - - - - - - - - - - - - - Get the global #GstMetaInfo describing the #GstReferenceTimestampMeta meta. - - - The #GstMetaInfo - - - - - - - - - - - Tests if you can safely set the buffer and / or buffer list of @sample. - - - - A #GstSample - - - - - Returns a writable copy of @sample. If the source sample is -already writable, this will simply return the same sample. - -Use this function to ensure that a sample can be safely modified before -making changes to it, for example before calling gst_sample_set_buffer() - -If the reference count of the source sample @sample is exactly one, the caller -is the sole owner and this function will return the sample object unchanged. - -If there is more than one reference on the object, a copy will be made using -gst_sample_copy(). The passed-in @sample will be unreffed in that case, and the -caller will now own a reference to the new returned sample object. - -In short, this function unrefs the sample in the argument and refs the sample -that it returns. Don't access the argument after calling this function unless -you have an additional reference to it. - - - - A #GstSample - - - - - Some functions in the GStreamer core might install a custom SIGSEGV handler -to better catch and report errors to the application. Currently this feature -is enabled by default when loading plugins. - -Applications might want to disable this behaviour with the -gst_segtrap_set_enabled() function. This is typically done if the application -wants to install its own handler without GStreamer interfering. - - - %TRUE if GStreamer is allowed to install a custom SIGSEGV handler. - - - - - Applications might want to disable/enable the SIGSEGV handling of -the GStreamer core. See gst_segtrap_is_enabled() for more information. - - - - - - - whether a custom SIGSEGV handler should be installed. - - - - - - Gets a string representing the given state transition. - - - a string with the name of the state - result. - - - - - a #GstStateChange to get the name of. - - - - - - - - - - - - - - - - - - - - - - - - - - Get a descriptive string for a given #GstStreamType - - - A string describing the stream type - - - - - a #GstStreamType - - - - - - Atomically modifies a pointer to point to a new structure. -The #GstStructure @oldstr_ptr is pointing to is freed and -@newstr is taken ownership over. - -Either @newstr and the value pointed to by @oldstr_ptr may be %NULL. - -It is a programming error if both @newstr and the value pointed to by -@oldstr_ptr refer to the same, non-%NULL structure. - - - %TRUE if @newstr was different from @oldstr_ptr - - - - - pointer to a place of - a #GstStructure to take - - - - a new #GstStructure - - - - - - Checks if the given type is already registered. - - - %TRUE if the type is already registered - - - - - name of the tag - - - - - - Returns the human-readable description of this tag, You must not change or -free this string. - - - the human-readable description of this tag - - - - - the tag - - - - - - Gets the flag of @tag. - - - the flag of this tag. - - - - - the tag - - - - - - Returns the human-readable name of this tag, You must not change or free -this string. - - - the human-readable name of this tag - - - - - the tag - - - - - - Gets the #GType used for this tag. - - - the #GType of this tag - - - - - the tag - - - - - - Checks if the given tag is fixed. A fixed tag can only contain one value. -Unfixed tags can contain lists of values. - - - %TRUE, if the given tag is fixed. - - - - - tag to check - - - - - - Copies the contents for the given tag into the value, -merging multiple values into one if multiple values are associated -with the tag. -You must g_value_unset() the value after use. - - - %TRUE, if a value was copied, %FALSE if the tag didn't exist in the - given list. - - - - - uninitialized #GValue to copy into - - - - list to get the tag from - - - - tag to read out - - - - - - - - - - - - - Tests if you can safely modify @taglist. It is only safe to modify taglist -when there is only one owner of the taglist - ie, the refcount is 1. - - - - a #GstTagList - - - - - Returns a writable copy of @taglist. - -If there is only one reference count on @taglist, the caller must be the -owner, and so this function will return the taglist object unchanged. If on -the other hand there is more than one reference on the object, a new taglist -object will be returned (which will be a copy of @taglist). The caller's -reference on @taglist will be removed, and instead the caller will own a -reference to the returned object. - -In short, this function unrefs the taglist in the argument and refs the -taglist that it returns. Don't access the argument after calling this -function. See also: gst_tag_list_ref(). - - - - a #GstTagList - - - - - This is a convenience function for the func argument of gst_tag_register(). -It concatenates all given strings using a comma. The tag must be registered -as a G_TYPE_STRING or this function will fail. - - - - - - - uninitialized GValue to store result in - - - - GValue to copy from - - - - - - This is a convenience function for the func argument of gst_tag_register(). -It creates a copy of the first value from the list. - - - - - - - uninitialized GValue to store result in - - - - GValue to copy from - - - - - - Registers a new tag type for the use with GStreamer's type system. If a type -with that name is already registered, that one is used. -The old registration may have used a different type however. So don't rely -on your supplied values. - -Important: if you do not supply a merge function the implication will be -that there can only be one single value for this tag in a tag list and -any additional values will silently be discarded when being added (unless -#GST_TAG_MERGE_REPLACE, #GST_TAG_MERGE_REPLACE_ALL, or -#GST_TAG_MERGE_PREPEND is used as merge mode, in which case the new -value will replace the old one in the list). - -The merge function will be called from gst_tag_list_copy_value() when -it is required that one or more values for a tag be condensed into -one single value. This may happen from gst_tag_list_get_string(), -gst_tag_list_get_int(), gst_tag_list_get_double() etc. What will happen -exactly in that case depends on how the tag was registered and if a -merge function was supplied and if so which one. - -Two default merge functions are provided: gst_tag_merge_use_first() and -gst_tag_merge_strings_with_comma(). - - - - - - - the name or identifier string - - - - a flag describing the type of tag info - - - - the type this data is in - - - - human-readable name - - - - a human-readable description about this tag - - - - function for merging multiple values of this tag, or %NULL - - - - - - Registers a new tag type for the use with GStreamer's type system. - -Same as gst_tag_register(), but @name, @nick, and @blurb must be -static strings or inlined strings, as they will not be copied. (GStreamer -plugins will be made resident once loaded, so this function can be used -even from dynamically loaded plugins.) - - - - - - - the name or identifier string (string constant) - - - - a flag describing the type of tag info - - - - the type this data is in - - - - human-readable name or short description (string constant) - - - - a human-readable description for this tag (string constant) - - - - function for merging multiple values of this tag, or %NULL - - - - - - Copy #GstToc with all subentries (deep copy). - - - - #GstToc to copy. - - - - - Copy #GstTocEntry with all subentries (deep copy). - - - - #GstTocEntry to copy. - - - - - - - - - - - - - - - - - - - Converts @type to a string representation. - - - Returns a human-readable string for @type. This string is - only for debugging purpose and should not be displayed in a user - interface. - - - - - a #GstTocEntryType. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get a list of all active tracer objects owned by the tracing framework for -the entirety of the run-time of the process or till gst_deinit() is called. - - - A #GList of -#GstTracer objects - - - - - - - Register @func to be called when the trace hook @detail is getting invoked. -Use %NULL for @detail to register to all hooks. - - - - - - - the tracer - - - - the detailed hook - - - - the callback - - - - - - - - - - - - - Registers a new typefind function to be used for typefinding. After -registering this function will be available for typefinding. -This function is typically called during an element's plugin initialization. - - - %TRUE on success, %FALSE otherwise - - - - - A #GstPlugin, or %NULL for a static typefind function - - - - The name for registering - - - - The rank (or importance) of this typefind function - - - - The #GstTypeFindFunction to use - - - - Optional comma-separated list of extensions - that could belong to this type - - - - Optionally the caps that could be returned when typefinding - succeeds - - - - Optional user data. This user data must be available until the plugin - is unloaded. - - - - a #GDestroyNotify that will be called on @data when the plugin - is unloaded. - - - - - - Checks if @type is plugin API. See gst_type_mark_as_plugin_api() for -details. - - - %TRUE if @type is plugin API or %FALSE otherwise. - - - - - a GType - - - - What #GstPluginAPIFlags the plugin was marked with - - - - - - Marks @type as plugin API. This should be called in `class_init` of -elements that expose new types (i.e. enums, flags or internal GObjects) via -properties, signals or pad templates. - -Types exposed by plugins are not automatically added to the documentation -as they might originate from another library and should in that case be -documented via that library instead. - -By marking a type as plugin API it will be included in the documentation of -the plugin that defines it. - - - - - - - a GType - - - - a set of #GstPluginAPIFlags to further inform cache generation. - - - - - - Forces GStreamer to re-scan its plugin paths and update the default -plugin registry. - -Applications will almost never need to call this function, it is only -useful if the application knows new plugins have been installed (or old -ones removed) since the start of the application (or, to be precise, the -first call to gst_init()) and the application wants to make use of any -newly-installed plugins without restarting the application. - -Applications should assume that the registry update is neither atomic nor -thread-safe and should therefore not have any dynamic pipelines running -(including the playbin and decodebin elements) and should also not create -any elements or access the GStreamer registry while the update is in -progress. - -Note that this function may block for a significant amount of time. - - - %TRUE if the registry has been updated successfully (does not - imply that there were changes), otherwise %FALSE. - - - - - Constructs a URI for a given valid protocol and location. - -Free-function: g_free - Use GstURI instead. - - - a new string for this URI. Returns %NULL if the - given URI protocol is not valid, or the given location is %NULL. - - - - - Protocol for URI - - - - Location for URI - - - - - - - - - - - - Parses a URI string into a new #GstUri object. Will return NULL if the URI -cannot be parsed. - - - A new #GstUri object, or NULL. - - - - - The URI string to parse. - - - - - - Parses a URI string into a new #GstUri object. Will return NULL if the URI -cannot be parsed. This is identical to gst_uri_from_string() except that -the userinfo and fragment components of the URI will not be unescaped while -parsing. - -Use this when you need to extract a username and password from the userinfo -such as https://user:password@example.com since either may contain -a URI-escaped ':' character. gst_uri_from_string() will unescape the entire -userinfo component, which will make it impossible to know which ':' -delineates the username and password. - -The same applies to the fragment component of the URI, such as -https://example.com/path#fragment which may contain a URI-escaped '#'. - - - A new #GstUri object, or NULL. - - - - - The URI string to parse. - - - - - - Extracts the location out of a given valid URI, ie. the protocol and "://" -are stripped from the URI, which means that the location returned includes -the hostname if one is specified. The returned string must be freed using -g_free(). - -Free-function: g_free - - - the location for this URI. Returns - %NULL if the URI isn't valid. If the URI does not contain a location, an - empty string is returned. - - - - - A URI string - - - - - - Extracts the protocol out of a given valid URI. The returned string must be -freed using g_free(). - - - The protocol for this URI. - - - - - A URI string - - - - - - Checks if the protocol of a given valid URI matches @protocol. - - - %TRUE if the protocol matches. - - - - - a URI string - - - - a protocol string (e.g. "http") - - - - - - Tests if the given string is a valid URI identifier. URIs start with a valid -scheme followed by ":" and maybe a string identifying the location. - - - %TRUE if the string is a valid URI - - - - - A URI string - - - - - - This is a convenience function to join two URI strings and return the result. -The returned string should be g_free()'d after use. - - - A string representing the percent-encoded join of - the two URIs. - - - - - The percent-encoded base URI. - - - - The percent-encoded reference URI to join to the @base_uri. - - - - - - Checks if an element exists that supports the given URI protocol. Note -that a positive return value does not imply that a subsequent call to -gst_element_make_from_uri() is guaranteed to work. - - - %TRUE - - - - - Whether to check for a source or a sink - - - - Protocol that should be checked for (e.g. "http" or "smb") - - - - - - Tests if the given string is a valid protocol identifier. Protocols -must consist of alphanumeric characters, '+', '-' and '.' and must -start with a alphabetic character. See RFC 3986 Section 3.1. - - - %TRUE if the string is a valid protocol identifier, %FALSE otherwise. - - - - - A string - - - - - - Searches inside @array for @search_data by using the comparison function -@search_func. @array must be sorted ascending. - -As @search_data is always passed as second argument to @search_func it's -not required that @search_data has the same type as the array elements. - -The complexity of this search function is O(log (num_elements)). - - - The address of the found -element or %NULL if nothing was found - - - - - the sorted input array - - - - number of elements in the array - - - - size of every element in bytes - - - - function to compare two elements, @search_data will always be passed as second argument - - - - search mode that should be used - - - - element that should be found - - - - data to pass to @search_func - - - - - - Transforms a #gdouble to a fraction and simplifies -the result. - - - - - - - #gdouble to transform - - - - pointer to a #gint to hold the result numerator - - - - pointer to a #gint to hold the result denominator - - - - - - Dumps the buffer memory into a hex representation. Useful for debugging. - - - - - - - a #GstBuffer whose memory to dump - - - - - - Dumps the memory block into a hex representation. Useful for debugging. - - - - - - - a pointer to the memory to dump - - - - - - the size of the memory block to dump - - - - - - Adds the fractions @a_n/@a_d and @b_n/@b_d and stores -the result in @res_n and @res_d. - - - %FALSE on overflow, %TRUE otherwise. - - - - - Numerator of first value - - - - Denominator of first value - - - - Numerator of second value - - - - Denominator of second value - - - - Pointer to #gint to hold the result numerator - - - - Pointer to #gint to hold the result denominator - - - - - - Compares the fractions @a_n/@a_d and @b_n/@b_d and returns --1 if a < b, 0 if a = b and 1 if a > b. - - - -1 if a < b; 0 if a = b; 1 if a > b. - - - - - Numerator of first value - - - - Denominator of first value - - - - Numerator of second value - - - - Denominator of second value - - - - - - Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores -the result in @res_n and @res_d. - - - %FALSE on overflow, %TRUE otherwise. - - - - - Numerator of first value - - - - Denominator of first value - - - - Numerator of second value - - - - Denominator of second value - - - - Pointer to #gint to hold the result numerator - - - - Pointer to #gint to hold the result denominator - - - - - - Transforms a fraction to a #gdouble. - - - - - - - Fraction numerator as #gint - - - - Fraction denominator #gint - - - - pointer to a #gdouble for the result - - - - - - - - @value casted to #guint64 - - - - - The #gdouble value to convert guint64 double - - - - - - Get a property of type %GST_TYPE_ARRAY and transform it into a -#GValueArray. This allow language bindings to get GST_TYPE_ARRAY -properties which are otherwise not an accessible type. - - - - - - - the object to set the array to - - - - the name of the property to set - - - - a return #GValueArray - - - - - - Get a timestamp as GstClockTime to be used for interval measurements. -The timestamp should not be interpreted in any other way. - - - the timestamp - - - - - Calculates the greatest common divisor of @a -and @b. - - - Greatest common divisor of @a and @b - - - - - First value as #gint - - - - Second value as #gint - - - - - - Calculates the greatest common divisor of @a -and @b. - - - Greatest common divisor of @a and @b - - - - - First value as #gint64 - - - - Second value as #gint64 - - - - - - Return a constantly incrementing group id. - -This function is used to generate a new group-id for the -stream-start event. - -This function never returns %GST_GROUP_ID_INVALID (which is 0) - - - A constantly incrementing unsigned integer, which might -overflow back to 0 at some point. - - - - - - - @value casted to #gdouble - - - - - The #guint64 value to convert to double - - - - - - Compare two sequence numbers, handling wraparound. - -The current implementation just returns (gint32)(@s1 - @s2). - - - A negative number if @s1 is before @s2, 0 if they are equal, or a -positive number if @s1 is after @s2. - - - - - A sequence number. - - - - Another sequence number. - - - - - - Return a constantly incrementing sequence number. - -This function is used internally to GStreamer to be able to determine which -events and messages are "the same". For example, elements may set the seqnum -on a segment-done message to be the same as that of the last seek event, to -indicate that event and the message correspond to the same segment. - -This function never returns %GST_SEQNUM_INVALID (which is 0). - - - A constantly incrementing 32-bit unsigned integer, which might -overflow at some point. Use gst_util_seqnum_compare() to make sure -you handle wraparound correctly. - - - - - Converts the string value to the type of the objects argument and -sets the argument with it. - -Note that this function silently returns if @object has no property named -@name or when @value cannot be converted to the type of the property. - - - - - - - the object to set the argument of - - - - the name of the argument to set - - - - the string value to set - - - - - - Transfer a #GValueArray to %GST_TYPE_ARRAY and set this value on the -specified property name. This allow language bindings to set GST_TYPE_ARRAY -properties which are otherwise not an accessible type. - - - - - - - the object to set the array to - - - - the name of the property to set - - - - a #GValueArray containing the values - - - - - - Converts the string to the type of the value and -sets the value with it. - -Note that this function is dangerous as it does not return any indication -if the conversion worked or not. - - - - - - - the value to set - - - - the string to get the value from - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. - -This function can potentially be very slow if val and num are both -greater than G_MAXUINT32. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer it is truncated. See also -gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(), -gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), -gst_util_uint64_scale_int_ceil(). - - - - - the number to scale - - - - the numerator of the scale ratio - - - - the denominator of the scale ratio - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. - -This function can potentially be very slow if val and num are both -greater than G_MAXUINT32. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer, it is rounded up. See also -gst_util_uint64_scale(), gst_util_uint64_scale_round(), -gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), -gst_util_uint64_scale_int_ceil(). - - - - - the number to scale - - - - the numerator of the scale ratio - - - - the denominator of the scale ratio - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. @num must be non-negative and -@denom must be positive. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer, it is truncated. See also -gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(), -gst_util_uint64_scale(), gst_util_uint64_scale_round(), -gst_util_uint64_scale_ceil(). - - - - - guint64 (such as a #GstClockTime) to scale. - - - - numerator of the scale factor. - - - - denominator of the scale factor. - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. @num must be non-negative and -@denom must be positive. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer, it is rounded up. See also -gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), -gst_util_uint64_scale(), gst_util_uint64_scale_round(), -gst_util_uint64_scale_ceil(). - - - - - guint64 (such as a #GstClockTime) to scale. - - - - numerator of the scale factor. - - - - denominator of the scale factor. - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. @num must be non-negative and -@denom must be positive. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer, it is rounded to the nearest integer -(half-way cases are rounded up). See also gst_util_uint64_scale_int(), -gst_util_uint64_scale_int_ceil(), gst_util_uint64_scale(), -gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(). - - - - - guint64 (such as a #GstClockTime) to scale. - - - - numerator of the scale factor. - - - - denominator of the scale factor. - - - - - - Scale @val by the rational number @num / @denom, avoiding overflows and -underflows and without loss of precision. - -This function can potentially be very slow if val and num are both -greater than G_MAXUINT32. - - - @val * @num / @denom. In the case of an overflow, this -function returns G_MAXUINT64. If the result is not exactly -representable as an integer, it is rounded to the nearest integer -(half-way cases are rounded up). See also gst_util_uint64_scale(), -gst_util_uint64_scale_ceil(), gst_util_uint64_scale_int(), -gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(). - - - - - the number to scale - - - - the numerator of the scale ratio - - - - the denominator of the scale ratio - - - - - - Determines if @value1 and @value2 can be compared. - - - %TRUE if the values can be compared - - - - - a value to compare - - - - another value to compare - - - - - - Determines if intersecting two values will produce a valid result. -Two values will produce a valid intersection if they have the same -type. - - - %TRUE if the values can intersect - - - - - a value to intersect - - - - another value to intersect - - - - - - Checks if it's possible to subtract @subtrahend from @minuend. - - - %TRUE if a subtraction is possible - - - - - the value to subtract from - - - - the value to subtract - - - - - - Determines if @value1 and @value2 can be non-trivially unioned. -Any two values can be trivially unioned by adding both of them -to a GstValueList. However, certain types have the possibility -to be unioned in a simpler way. For example, an integer range -and an integer can be unioned if the integer is a subset of the -integer range. If there is the possibility that two values can -be unioned, this function returns %TRUE. - - - %TRUE if there is a function allowing the two values to -be unioned. - - - - - a value to union - - - - another value to union - - - - - - Compares @value1 and @value2. If @value1 and @value2 cannot be -compared, the function returns GST_VALUE_UNORDERED. Otherwise, -if @value1 is greater than @value2, GST_VALUE_GREATER_THAN is returned. -If @value1 is less than @value2, GST_VALUE_LESS_THAN is returned. -If the values are equal, GST_VALUE_EQUAL is returned. - - - comparison result - - - - - a value to compare - - - - another value to compare - - - - - - Tries to deserialize a string into the type specified by the given GValue. -If the operation succeeds, %TRUE is returned, %FALSE otherwise. - - - %TRUE on success - - - - - #GValue to fill with contents of - deserialization - - - - string to deserialize - - - - - - Fixate @src into a new value @dest. -For ranges, the first element is taken. For lists and arrays, the -first item is fixated and returned. -If @src is already fixed, this function returns %FALSE. - - - %TRUE if @dest contains a fixated version of @src. - - - - - the #GValue destination - - - - the #GValue to fixate - - - - - - Multiplies the two #GValue items containing a #GST_TYPE_FRACTION and sets -@product to the product of the two fractions. - - - %FALSE in case of an error (like integer overflow), %TRUE otherwise. - - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - - - Subtracts the @subtrahend from the @minuend and sets @dest to the result. - - - %FALSE in case of an error (like integer overflow), %TRUE otherwise. - - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - - - Gets the bitmask specified by @value. - - - the bitmask. - - - - - a GValue initialized to #GST_TYPE_BITMASK - - - - - - Receives a #GstBuffer as the value of @v. Does not return a reference to -the buffer, so the pointer is only valid for as long as the caller owns -a reference to @v. - - - - a #GValue to query - - - - - Gets the contents of @value. The reference count of the returned -#GstCaps will not be modified, therefore the caller must take one -before getting rid of the @value. - - - the contents of @value - - - - - a GValue initialized to GST_TYPE_CAPS - - - - - - Gets the contents of @value. - - - the contents of @value - - - - - a GValue initialized to GST_TYPE_CAPS_FEATURES - - - - - - Gets the maximum of the range specified by @value. - - - the maximum of the range - - - - - a GValue initialized to GST_TYPE_DOUBLE_RANGE - - - - - - Gets the minimum of the range specified by @value. - - - the minimum of the range - - - - - a GValue initialized to GST_TYPE_DOUBLE_RANGE - - - - - - Retrieve the flags field of a GstFlagSet @value. - - - the flags field of the flagset instance. - - - - - a GValue initialized to #GST_TYPE_FLAG_SET - - - - - - Retrieve the mask field of a GstFlagSet @value. - - - the mask field of the flagset instance. - - - - - a GValue initialized to #GST_TYPE_FLAG_SET - - - - - - Gets the denominator of the fraction specified by @value. - - - the denominator of the fraction. - - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - - - Gets the numerator of the fraction specified by @value. - - - the numerator of the fraction. - - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - - - Gets the maximum of the range specified by @value. - - - the maximum of the range - - - - - a GValue initialized to GST_TYPE_FRACTION_RANGE - - - - - - Gets the minimum of the range specified by @value. - - - the minimum of the range - - - - - a GValue initialized to GST_TYPE_FRACTION_RANGE - - - - - - Gets the maximum of the range specified by @value. - - - the maximum of the range - - - - - a GValue initialized to GST_TYPE_INT64_RANGE - - - - - - Gets the minimum of the range specified by @value. - - - the minimum of the range - - - - - a GValue initialized to GST_TYPE_INT64_RANGE - - - - - - Gets the step of the range specified by @value. - - - the step of the range - - - - - a GValue initialized to GST_TYPE_INT64_RANGE - - - - - - Gets the maximum of the range specified by @value. - - - the maximum of the range - - - - - a GValue initialized to GST_TYPE_INT_RANGE - - - - - - Gets the minimum of the range specified by @value. - - - the minimum of the range - - - - - a GValue initialized to GST_TYPE_INT_RANGE - - - - - - Gets the step of the range specified by @value. - - - the step of the range - - - - - a GValue initialized to GST_TYPE_INT_RANGE - - - - - - Receives a #GstSample as the value of @v. Does not return a reference to -the sample, so the pointer is only valid for as long as the caller owns -a reference to @v. - - - - a #GValue to query - - - - - Gets the contents of @value. - - - the contents of @value - - - - - a GValue initialized to GST_TYPE_STRUCTURE - - - - - - Initialises the target value to be of the same type as source and then copies -the contents from source to target. - - - - - - - the target value - - - - the source value - - - - - - Calculates the intersection of two values. If the values have -a non-empty intersection, the value representing the intersection -is placed in @dest, unless %NULL. If the intersection is non-empty, -@dest is not modified. - - - %TRUE if the intersection is non-empty - - - - - - a uninitialized #GValue that will hold the calculated - intersection value. May be %NULL if the resulting set if not - needed. - - - - a value to intersect - - - - another value to intersect - - - - - - Tests if the given GValue, if available in a GstStructure (or any other -container) contains a "fixed" (which means: one value) or an "unfixed" -(which means: multiple possible values, such as data lists or data -ranges) value. - - - true if the value is "fixed". - - - - - the #GValue to check - - - - - - Check that @value1 is a subset of @value2. - - - %TRUE is @value1 is a subset of @value2 - - - - - a #GValue - - - - a #GValue - - - - - - Registers functions to perform calculations on #GValue items of a given -type. Each type can only be added once. - - - - - - - structure containing functions to register - - - - - - tries to transform the given @value into a string representation that allows -getting back this string later on using gst_value_deserialize(). - -Free-function: g_free - - - the serialization for @value -or %NULL if none exists - - - - - a #GValue to serialize - - - - - - Sets @value to the bitmask specified by @bitmask. - - - - - - - a GValue initialized to #GST_TYPE_BITMASK - - - - the bitmask - - - - - - Sets @b as the value of @v. Caller retains reference to buffer. - - - - a #GValue to receive the data - - - a #GstBuffer to assign to the GstValue - - - - - Sets the contents of @value to @caps. A reference to the -provided @caps will be taken by the @value. - - - - - - - a GValue initialized to GST_TYPE_CAPS - - - - the caps to set the value to - - - - - - Sets the contents of @value to @features. - - - - - - - a GValue initialized to GST_TYPE_CAPS_FEATURES - - - - the features to set the value to - - - - - - Sets @value to the range specified by @start and @end. - - - - - - - a GValue initialized to GST_TYPE_DOUBLE_RANGE - - - - the start of the range - - - - the end of the range - - - - - - Sets @value to the flags and mask values provided in @flags and @mask. -The @flags value indicates the values of flags, the @mask represents -which bits in the flag value have been set, and which are "don't care" - - - - - - - a GValue initialized to %GST_TYPE_FLAG_SET - - - - The value of the flags set or unset - - - - The mask indicate which flags bits must match for comparisons - - - - - - Sets @value to the fraction specified by @numerator over @denominator. -The fraction gets reduced to the smallest numerator and denominator, -and if necessary the sign is moved to the numerator. - - - - - - - a GValue initialized to #GST_TYPE_FRACTION - - - - the numerator of the fraction - - - - the denominator of the fraction - - - - - - Sets @value to the range specified by @start and @end. - - - - - - - a GValue initialized to GST_TYPE_FRACTION_RANGE - - - - the start of the range (a GST_TYPE_FRACTION GValue) - - - - the end of the range (a GST_TYPE_FRACTION GValue) - - - - - - Sets @value to the range specified by @numerator_start/@denominator_start -and @numerator_end/@denominator_end. - - - - - - - a GValue initialized to GST_TYPE_FRACTION_RANGE - - - - the numerator start of the range - - - - the denominator start of the range - - - - the numerator end of the range - - - - the denominator end of the range - - - - - - Sets @value to the range specified by @start and @end. - - - - - - - a GValue initialized to GST_TYPE_INT64_RANGE - - - - the start of the range - - - - the end of the range - - - - - - Sets @value to the range specified by @start, @end and @step. - - - - - - - a GValue initialized to GST_TYPE_INT64_RANGE - - - - the start of the range - - - - the end of the range - - - - the step of the range - - - - - - Sets @value to the range specified by @start and @end. - - - - - - - a GValue initialized to GST_TYPE_INT_RANGE - - - - the start of the range - - - - the end of the range - - - - - - Sets @value to the range specified by @start, @end and @step. - - - - - - - a GValue initialized to GST_TYPE_INT_RANGE - - - - the start of the range - - - - the end of the range - - - - the step of the range - - - - - - Sets @b as the value of @v. Caller retains reference to sample. - - - - a #GValue to receive the data - - - a #GstSample to assign to the GstValue - - - - - Sets the contents of @value to @structure. - - - - - - - a GValue initialized to GST_TYPE_STRUCTURE - - - - the structure to set the value to - - - - - - Subtracts @subtrahend from @minuend and stores the result in @dest. -Note that this means subtraction as in sets, not as in mathematics. - - - %TRUE if the subtraction is not empty - - - - - the destination value - for the result if the subtraction is not empty. May be %NULL, - in which case the resulting set will not be computed, which can - give a fair speedup. - - - - the value to subtract from - - - - the value to subtract - - - - - - Sets @b as the value of @v. Caller gives away reference to buffer. - - - - a #GValue to receive the data - - - a #GstBuffer to assign to the GstValue - - - - - Sets @b as the value of @v. Caller gives away reference to sample. - - - - a #GValue to receive the data - - - a #GstSample to assign to the GstValue - - - - - Creates a GValue corresponding to the union of @value1 and @value2. - - - %TRUE if the union succeeded. - - - - - the destination value - - - - a value to union - - - - another value to union - - - - - - Gets the version number of the GStreamer library. - - - - - - - pointer to a guint to store the major version number - - - - pointer to a guint to store the minor version number - - - - pointer to a guint to store the micro version number - - - - pointer to a guint to store the nano version number - - - - - - This function returns a string that is useful for describing this version -of GStreamer to the outside world: user agent strings, logging, ... - - - a newly allocated string describing this version - of GStreamer. - - - - - diff --git a/gir-files/GstApp-1.0.gir b/gir-files/GstApp-1.0.gir deleted file mode 100644 index 36853f513..000000000 --- a/gir-files/GstApp-1.0.gir +++ /dev/null @@ -1,1967 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Appsink is a sink plugin that supports many different methods for making -the application get a handle on the GStreamer data in a pipeline. Unlike -most GStreamer elements, Appsink provides external API functions. - -appsink can be used by linking to the gstappsink.h header file to access the -methods or by using the appsink action signals and properties. - -The normal way of retrieving samples from appsink is by using the -gst_app_sink_pull_sample() and gst_app_sink_pull_preroll() methods. -These methods block until a sample becomes available in the sink or when the -sink is shut down or reaches EOS. There are also timed variants of these -methods, gst_app_sink_try_pull_sample() and gst_app_sink_try_pull_preroll(), -which accept a timeout parameter to limit the amount of time to wait. - -Appsink will internally use a queue to collect buffers from the streaming -thread. If the application is not pulling samples fast enough, this queue -will consume a lot of memory over time. The "max-buffers" property can be -used to limit the queue size. The "drop" property controls whether the -streaming thread blocks or if older buffers are dropped when the maximum -queue size is reached. Note that blocking the streaming thread can negatively -affect real-time performance and should be avoided. - -If a blocking behaviour is not desirable, setting the "emit-signals" property -to %TRUE will make appsink emit the "new-sample" and "new-preroll" signals -when a sample can be pulled without blocking. - -The "caps" property on appsink can be used to control the formats that -appsink can receive. This property can contain non-fixed caps, the format of -the pulled samples can be obtained by getting the sample caps. - -If one of the pull-preroll or pull-sample methods return %NULL, the appsink -is stopped or in the EOS state. You can check for the EOS state with the -"eos" property or with the gst_app_sink_is_eos() method. - -The eos signal can also be used to be informed when the EOS state is reached -to avoid polling. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample(). - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - -This function blocks until a preroll sample or EOS is received or the appsink -element is set to the READY/NULL state. - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample(). - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS -condition. - -This function blocks until a preroll sample or EOS is received, the appsink -element is set to the READY/NULL state, or the timeout expires. - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for the preroll sample - - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state or the timeout expires. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS -condition. - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. -Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for a sample - - - - - - Check if @appsink supports buffer lists. - - - %TRUE if @appsink supports buffer lists. - - - - - a #GstAppSink - - - - - - Get the configured caps on @appsink. - - - the #GstCaps accepted by the sink. gst_caps_unref() after usage. - - - - - a #GstAppSink - - - - - - Check if @appsink will drop old buffers when the maximum amount of queued -buffers is reached. - - - %TRUE if @appsink is dropping old buffers when the queue is -filled. - - - - - a #GstAppSink - - - - - - Check if appsink will emit the "new-preroll" and "new-sample" signals. - - - %TRUE if @appsink is emitting the "new-preroll" and "new-sample" -signals. - - - - - a #GstAppSink - - - - - - Get the maximum amount of buffers that can be queued in @appsink. - - - The maximum amount of buffers that can be queued. - - - - - a #GstAppSink - - - - - - Check if @appsink will wait for all buffers to be consumed when an EOS is -received. - - - %TRUE if @appsink will wait for all buffers to be consumed when an -EOS is received. - - - - - a #GstAppSink - - - - - - Check if @appsink is EOS, which is when no more samples can be pulled because -an EOS event was received. - -This function also returns %TRUE when the appsink is not in the PAUSED or -PLAYING state. - - - %TRUE if no more samples can be pulled and the appsink is EOS. - - - - - a #GstAppSink - - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample(). - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - -This function blocks until a preroll sample or EOS is received or the appsink -element is set to the READY/NULL state. - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - Instruct @appsink to enable or disable buffer list support. - -For backwards-compatibility reasons applications need to opt in -to indicate that they will be able to handle buffer lists. - - - - - - - a #GstAppSink - - - - enable or disable buffer list support - - - - - - Set callbacks which will be executed for each new preroll, new sample and eos. -This is an alternative to using the signals, it has lower overhead and is thus -less expensive, but also less flexible. - -If callbacks are installed, no signals will be emitted for performance -reasons. - -Before 1.16.3 it was not possible to change the callbacks in a thread-safe -way. - - - - - - - a #GstAppSink - - - - the callbacks - - - - a user_data argument for the callbacks - - - - a destroy notify function - - - - - - Set the capabilities on the appsink element. This function takes -a copy of the caps structure. After calling this method, the sink will only -accept caps that match @caps. If @caps is non-fixed, or incomplete, -you must check the caps on the samples to get the actual used caps. - - - - - - - a #GstAppSink - - - - caps to set - - - - - - Instruct @appsink to drop old buffers when the maximum amount of queued -buffers is reached. - - - - - - - a #GstAppSink - - - - the new state - - - - - - Make appsink emit the "new-preroll" and "new-sample" signals. This option is -by default disabled because signal emission is expensive and unneeded when -the application prefers to operate in pull mode. - - - - - - - a #GstAppSink - - - - the new state - - - - - - Set the maximum amount of buffers that can be queued in @appsink. After this -amount of buffers are queued in appsink, any more buffers will block upstream -elements until a sample is pulled from @appsink. - - - - - - - a #GstAppSink - - - - the maximum number of buffers to queue - - - - - - Instruct @appsink to wait for all buffers to be consumed when an EOS is received. - - - - - - - a #GstAppSink - - - - the new state - - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample(). - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS -condition. - -This function blocks until a preroll sample or EOS is received, the appsink -element is set to the READY/NULL state, or the timeout expires. - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for the preroll sample - - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state or the timeout expires. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS -condition. - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. -Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for a sample - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Signal that the end-of-stream has been reached. This signal is emitted from -the streaming thread. - - - - - - Signal that a new preroll sample is available. - -This signal is emitted from the streaming thread and only when the -"emit-signals" property is %TRUE. - -The new preroll sample can be retrieved with the "pull-preroll" action -signal or gst_app_sink_pull_preroll() either from this signal callback -or from any other thread. - -Note that this signal is only emitted when the "emit-signals" property is -set to %TRUE, which it is not by default for performance reasons. - - - - - - Signal that a new sample is available. - -This signal is emitted from the streaming thread and only when the -"emit-signals" property is %TRUE. - -The new sample can be retrieved with the "pull-sample" action -signal or gst_app_sink_pull_sample() either from this signal callback -or from any other thread. - -Note that this signal is only emitted when the "emit-signals" property is -set to %TRUE, which it is not by default for performance reasons. - - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample() or the "pull-sample" action signal. - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - -This function blocks until a preroll sample or EOS is received or the appsink -element is set to the READY/NULL state. - - a #GstSample or NULL when the appsink is stopped or EOS. - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered samples will be put in a queue so that the application -can pull samples at its own rate. - -Note that when the application does not pull samples fast enough, the -queued samples could consume a lot of memory, especially when dealing with -raw video frames. It's possible to control the behaviour of the queue with -the "drop" and "max-buffers" properties. - -If an EOS event was received before any buffers, this function returns -%NULL. Use gst_app_sink_is_eos () to check for the EOS condition. - - a #GstSample or NULL when the appsink is stopped or EOS. - - - - - Get the last preroll sample in @appsink. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling gst_app_sink_pull_sample() or the "pull-sample" action signal. - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS -condition. - -This function blocks until a preroll sample or EOS is received, the appsink -element is set to the READY/NULL state, or the timeout expires. - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. - - - - - the maximum amount of time to wait for the preroll sample - - - - - - This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state or the timeout expires. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered samples will be put in a queue so that the application -can pull samples at its own rate. - -Note that when the application does not pull samples fast enough, the -queued samples could consume a lot of memory, especially when dealing with -raw video frames. It's possible to control the behaviour of the queue with -the "drop" and "max-buffers" properties. - -If an EOS event was received before any buffers or the timeout expires, -this function returns %NULL. Use gst_app_sink_is_eos () to check -for the EOS condition. - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. - - - - - the maximum amount of time to wait for a sample - - - - - - - A set of callbacks that can be installed on the appsink with -gst_app_sink_set_callbacks(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - - - - - a #GstSample or NULL when the appsink is stopped or EOS. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - - - - - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. - Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for the preroll sample - - - - - - - - - - a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires. -Call gst_sample_unref() after usage. - - - - - a #GstAppSink - - - - the maximum amount of time to wait for a sample - - - - - - - - - - - - - - - - The appsrc element can be used by applications to insert data into a -GStreamer pipeline. Unlike most GStreamer elements, appsrc provides -external API functions. - -appsrc can be used by linking with the libgstapp library to access the -methods directly or by using the appsrc action signals. - -Before operating appsrc, the caps property must be set to fixed caps -describing the format of the data that will be pushed with appsrc. An -exception to this is when pushing buffers with unknown caps, in which case no -caps should be set. This is typically true of file-like sources that push raw -byte buffers. If you don't want to explicitly set the caps, you can use -gst_app_src_push_sample. This method gets the caps associated with the -sample and sets them on the appsrc replacing any previously set caps (if -different from sample's caps). - -The main way of handing data to the appsrc element is by calling the -gst_app_src_push_buffer() method or by emitting the push-buffer action signal. -This will put the buffer onto a queue from which appsrc will read from in its -streaming thread. It is important to note that data transport will not happen -from the thread that performed the push-buffer call. - -The "max-bytes" property controls how much data can be queued in appsrc -before appsrc considers the queue full. A filled internal queue will always -signal the "enough-data" signal, which signals the application that it should -stop pushing data into appsrc. The "block" property will cause appsrc to -block the push-buffer method until free data becomes available again. - -When the internal queue is running out of data, the "need-data" signal is -emitted, which signals the application that it should start pushing more data -into appsrc. - -In addition to the "need-data" and "enough-data" signals, appsrc can emit the -"seek-data" signal when the "stream-mode" property is set to "seekable" or -"random-access". The signal argument will contain the new desired position in -the stream expressed in the unit set with the "format" property. After -receiving the seek-data signal, the application should push-buffers from the -new position. - -These signals allow the application to operate the appsrc in two different -ways: - -The push mode, in which the application repeatedly calls the push-buffer/push-sample -method with a new buffer/sample. Optionally, the queue size in the appsrc -can be controlled with the enough-data and need-data signals by respectively -stopping/starting the push-buffer/push-sample calls. This is a typical -mode of operation for the stream-type "stream" and "seekable". Use this -mode when implementing various network protocols or hardware devices. - -The pull mode, in which the need-data signal triggers the next push-buffer call. -This mode is typically used in the "random-access" stream-type. Use this -mode for file access or other randomly accessible sources. In this mode, a -buffer of exactly the amount of bytes given by the need-data signal should be -pushed into appsrc. - -In all modes, the size property on appsrc should contain the total stream -size in bytes. Setting this property is mandatory in the random-access mode. -For the stream and seekable modes, setting this property is optional but -recommended. - -When the application has finished pushing data into appsrc, it should call -gst_app_src_end_of_stream() or emit the end-of-stream action signal. After -this call, no more buffers can be pushed into appsrc until a flushing seek -occurs or the state of the appsrc has gone through READY. - - - - Indicates to the appsrc element that the last buffer queued in the -element is the last buffer of the stream. - - - #GST_FLOW_OK when the EOS was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. - - - - - a #GstAppSrc - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Adds a buffer to the queue of buffers that the appsrc element will -push to its source pad. This function takes ownership of the buffer. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBuffer to push - - - - - - Adds a buffer list to the queue of buffers and buffer lists that the -appsrc element will push to its source pad. This function takes ownership -of @buffer_list. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer list was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBufferList to push - - - - - - Extract a buffer from the provided sample and adds it to the queue of -buffers that the appsrc element will push to its source pad. Any -previous caps that were set on appsrc will be replaced by the caps -associated with the sample if not equal. - -This function does not take ownership of the -sample so the sample needs to be unreffed after calling this function. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstSample from which buffer and caps may be -extracted - - - - - - - - - - - - - - - - - - - - Indicates to the appsrc element that the last buffer queued in the -element is the last buffer of the stream. - - - #GST_FLOW_OK when the EOS was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. - - - - - a #GstAppSrc - - - - - - Get the configured caps on @appsrc. - - - the #GstCaps produced by the source. gst_caps_unref() after usage. - - - - - a #GstAppSrc - - - - - - Get the number of currently queued bytes inside @appsrc. - - - The number of currently queued bytes. - - - - - a #GstAppSrc - - - - - - Get the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is -not known. - - - the duration of the stream previously set with gst_app_src_set_duration(); - - - - - a #GstAppSrc - - - - - - Check if appsrc will emit the "new-preroll" and "new-buffer" signals. - - - %TRUE if @appsrc is emitting the "new-preroll" and "new-buffer" -signals. - - - - - a #GstAppSrc - - - - - - Retrieve the min and max latencies in @min and @max respectively. - - - - - - - a #GstAppSrc - - - - the min latency - - - - the max latency - - - - - - Get the maximum amount of bytes that can be queued in @appsrc. - - - The maximum amount of bytes that can be queued. - - - - - a #GstAppSrc - - - - - - Get the size of the stream in bytes. A value of -1 means that the size is -not known. - - - the size of the stream previously set with gst_app_src_set_size(); - - - - - a #GstAppSrc - - - - - - Get the stream type. Control the stream type of @appsrc -with gst_app_src_set_stream_type(). - - - the stream type. - - - - - a #GstAppSrc - - - - - - Adds a buffer to the queue of buffers that the appsrc element will -push to its source pad. This function takes ownership of the buffer. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBuffer to push - - - - - - Adds a buffer list to the queue of buffers and buffer lists that the -appsrc element will push to its source pad. This function takes ownership -of @buffer_list. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer list was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBufferList to push - - - - - - Extract a buffer from the provided sample and adds it to the queue of -buffers that the appsrc element will push to its source pad. Any -previous caps that were set on appsrc will be replaced by the caps -associated with the sample if not equal. - -This function does not take ownership of the -sample so the sample needs to be unreffed after calling this function. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstSample from which buffer and caps may be -extracted - - - - - - Set callbacks which will be executed when data is needed, enough data has -been collected or when a seek should be performed. -This is an alternative to using the signals, it has lower overhead and is thus -less expensive, but also less flexible. - -If callbacks are installed, no signals will be emitted for performance -reasons. - -Before 1.16.3 it was not possible to change the callbacks in a thread-safe -way. - - - - - - - a #GstAppSrc - - - - the callbacks - - - - a user_data argument for the callbacks - - - - a destroy notify function - - - - - - Set the capabilities on the appsrc element. This function takes -a copy of the caps structure. After calling this method, the source will -only produce caps that match @caps. @caps must be fixed and the caps on the -buffers must match the caps or left NULL. - - - - - - - a #GstAppSrc - - - - caps to set - - - - - - Set the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is -not known. - - - - - - - a #GstAppSrc - - - - the duration to set - - - - - - Make appsrc emit the "new-preroll" and "new-buffer" signals. This option is -by default disabled because signal emission is expensive and unneeded when -the application prefers to operate in pull mode. - - - - - - - a #GstAppSrc - - - - the new state - - - - - - Configure the @min and @max latency in @src. If @min is set to -1, the -default latency calculations for pseudo-live sources will be used. - - - - - - - a #GstAppSrc - - - - the min latency - - - - the max latency - - - - - - Set the maximum amount of bytes that can be queued in @appsrc. -After the maximum amount of bytes are queued, @appsrc will emit the -"enough-data" signal. - - - - - - - a #GstAppSrc - - - - the maximum number of bytes to queue - - - - - - Set the size of the stream in bytes. A value of -1 means that the size is -not known. - - - - - - - a #GstAppSrc - - - - the size to set - - - - - - Set the stream type on @appsrc. For seekable streams, the "seek" signal must -be connected to. - -A stream_type stream - - - - - - - a #GstAppSrc - - - - the new state - - - - - - When max-bytes are queued and after the enough-data signal has been emitted, -block any further push-buffer calls until the amount of queued bytes drops -below the max-bytes limit. - - - - The GstCaps that will negotiated downstream and will be put -on outgoing buffers. - - - - The number of currently queued bytes inside appsrc. - - - - The total duration in nanoseconds of the data stream. If the total duration is known, it -is recommended to configure it with this property. - - - - Make appsrc emit the "need-data", "enough-data" and "seek-data" signals. -This option is by default enabled for backwards compatibility reasons but -can disabled when needed because signal emission is expensive. - - - - The format to use for segment events. When the source is producing -timestamped buffers this property should be set to GST_FORMAT_TIME. - - - - When enabled, appsrc will check GstSegment in GstSample which was -pushed via gst_app_src_push_sample() or "push-sample" signal action. -If a GstSegment is changed, corresponding segment event will be followed -by next data flow. - -FIXME: currently only GST_FORMAT_TIME format is supported and therefore -GstAppSrc::format should be time. However, possibly #GstAppSrc can support -other formats. - - - - Instruct the source to behave like a live source. This includes that it -will only push out buffers in the PLAYING state. - - - - The maximum amount of bytes that can be queued internally. -After the maximum amount of bytes are queued, appsrc will emit the -"enough-data" signal. - - - - - - - The minimum latency of the source. A value of -1 will use the default -latency calculations of #GstBaseSrc. - - - - Make appsrc emit the "need-data" signal when the amount of bytes in the -queue drops below this percentage of max-bytes. - - - - The total size in bytes of the data stream. If the total size is known, it -is recommended to configure it with this property. - - - - The type of stream that this source is producing. For seekable streams the -application should connect to the seek-data signal. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A set of callbacks that can be installed on the appsrc with -gst_app_src_set_callbacks(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBuffer to push - - - - - - - - - - #GST_FLOW_OK when the EOS was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. - - - - - a #GstAppSrc - - - - - - - - - - #GST_FLOW_OK when the buffer was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstSample from which buffer and caps may be -extracted - - - - - - - - - - #GST_FLOW_OK when the buffer list was successfully queued. -#GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING. -#GST_FLOW_EOS when EOS occurred. - - - - - a #GstAppSrc - - - - a #GstBufferList to push - - - - - - - - - - - - - - - - The stream type. - - No seeking is supported in the stream, such as a -live stream. - - - The stream is seekable but seeking might not -be very fast, such as data from a webserver. - - - The stream is seekable and seeking is fast, -such as in a local file. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/gir-files/GstAudio-1.0.gir b/gir-files/GstAudio-1.0.gir deleted file mode 100644 index 852e506a9..000000000 --- a/gir-files/GstAudio-1.0.gir +++ /dev/null @@ -1,10671 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the #GstClock of @obj. - - - - a #GstAudioBaseSink - - - - - - - - - - - - Get the sink #GstPad of @obj. - - - - a #GstAudioBaseSink - - - - - - - - - - - - - - - - - - - - - - - - - - Get the #GstClock of @obj. - - - - a #GstAudioBaseSrc - - - - - - - - - - - - Get the source #GstPad of @obj. - - - - a #GstAudioBaseSrc - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Generic caps string for audio, for use in pad templates. - - - - string format that describes the sample layout, as string - (e.g. "S16LE", "S8", etc.) - - - - - - - - - - - - - - - - - - - - - - - - - - Maximum range of allowed channels, for use in template caps strings. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioDitherMethod, The dither method to use when -changing bit depth. -Default is #GST_AUDIO_DITHER_NONE. - - - - - #GST_TYPE_LIST, The channel mapping matrix. - -The matrix coefficients must be between -1 and 1: the number of rows is equal -to the number of output channels and the number of columns is equal to the -number of input channels. - -## Example matrix generation code -To generate the matrix using code: - -|[ -GValue v = G_VALUE_INIT; -GValue v2 = G_VALUE_INIT; -GValue v3 = G_VALUE_INIT; - -g_value_init (&v2, GST_TYPE_ARRAY); -g_value_init (&v3, G_TYPE_DOUBLE); -g_value_set_double (&v3, 1); -gst_value_array_append_value (&v2, &v3); -g_value_unset (&v3); -[ Repeat for as many double as your input channels - unset and reinit v3 ] -g_value_init (&v, GST_TYPE_ARRAY); -gst_value_array_append_value (&v, &v2); -g_value_unset (&v2); -[ Repeat for as many v2's as your output channels - unset and reinit v2] -g_object_set_property (G_OBJECT (audiomixmatrix), "matrix", &v); -g_value_unset (&v); -]| - - - - - #GstAudioNoiseShapingMethod, The noise shaping method to use -to mask noise from quantization errors. -Default is #GST_AUDIO_NOISE_SHAPING_NONE. - - - - - #G_TYPE_UINT, The quantization amount. Components will be -quantized to multiples of this value. -Default is 1 - - - - - #GstAudioResamplerMethod, The resampler method to use when -changing sample rates. -Default is #GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL. - - - - - - - - - - - - - - - - - - - - - - - - - - Utility function that audio decoder elements can use in case they encountered -a data processing error that may be fatal for the current "data unit" but -need not prevent subsequent decoding. Such errors are counted and if there -are too many, as configured in the context's max_errors, the pipeline will -post an error message and the application will be requested to stop further -media processing. Otherwise, it is considered a "glitch" and only a warning -is logged. In either case, @ret is set to the proper value to -return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK). - - - - the base audio decoder element that generates the error - - - element defined weight of the error, added to error count - - - like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) - - - error code defined for that domain (see #gstreamer-GstGError) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - variable to receive return value - - - - - - - - - - - - Gives the input segment of the element. - - - - audio decoder instance - - - - - Default maximum number of errors tolerated before signaling error. - - - - - Gives the output segment of the element. - - - - audio decoder instance - - - - - The name of the templates for the sink pad. - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - base audio codec instance - - - - - The name of the templates for the source pad. - - - - - Gives the pointer to the source #GstPad object of the element. - - - - base audio codec instance - - - - - - - - - - - - - - - - - - - Standard number of channels used in consumer audio. - - - - - Standard format used in consumer audio. - - - - - Standard sampling rate used in consumer audio. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gives the input segment of the element. - - - - base parse instance - - - - - Gives the output segment of the element. - - - - base parse instance - - - - - the name of the templates for the sink pad - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - audio encoder instance - - - - - the name of the templates for the source pad - - - - - Gives the pointer to the source #GstPad object of the element. - - - - audio encoder instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - List of all audio formats, for use in template caps strings. - -Formats are sorted by decreasing "quality", using these criteria by priority: - - depth - - width - - Float > Signed > Unsigned - - native endianness preferred - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Turns audio format string @s into the format string for native endianness. - - - - format string without endianness marker - - - - - Turns audio format string @s into the format string for other endianness. - - - - format string without endianness marker - - - - - Maximum range of allowed sample rates, for use in template caps strings. - - - - - G_TYPE_DOUBLE, B parameter of the cubic filter. -Values between 0.0 and 2.0 are accepted. 1.0 is the default. - -Below are some values of popular filters: - B C -Hermite 0.0 0.0 -Spline 1.0 0.0 -Catmull-Rom 0.0 1/2 - - - - - G_TYPE_DOUBLE, C parameter of the cubic filter. -Values between 0.0 and 2.0 are accepted. 0.0 is the default. - -See #GST_AUDIO_RESAMPLER_OPT_CUBIC_B for some more common values - - - - - G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default. - - - - - GST_TYPE_AUDIO_RESAMPLER_INTERPOLATION: how the filter coefficients should be - interpolated. -GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC is default. - - - - - GST_TYPE_AUDIO_RESAMPLER_FILTER_MODE: how the filter tables should be -constructed. -GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is the default. - - - - - G_TYPE_UINT: the amount of memory to use for full filter tables before -switching to interpolated filter tables. -1048576 is the default. - - - - - G_TYPE_UINT, oversampling to use when interpolating filters -8 is the default. - - - - - G_TYPE_DOUBLE: The maximum allowed phase error when switching sample -rates. -0.1 is the default. - - - - - G_TYPE_INT: the number of taps to use for the filter. -0 is the default and selects the taps automatically. - - - - - G_TYPE_DOUBLE, stopband attenuation in decibels. The attenuation -after the stopband for the kaiser window. 85 dB is the default. - - - - - G_TYPE_DOUBLE, transition bandwidth. The width of the -transition band for the kaiser window. 0.087 is the default. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses must use (a subclass of) #GstAudioAggregatorPad for both -their source and sink pads, -gst_element_class_add_static_pad_template_with_gtype() is a convenient -helper. - -#GstAudioAggregator can perform conversion on the data arriving -on its sink pads, based on the format expected downstream: in order -to enable that behaviour, the GType of the sink pads must either be -a (subclass of) #GstAudioAggregatorConvertPad to use the default -#GstAudioConverter implementation, or a subclass of #GstAudioAggregatorPad -implementing #GstAudioAggregatorPadClass.convert_buffer. - -To allow for the output caps to change, the mechanism is the same as -above, with the GType of the source pad. - -See #GstAudioMixer for an example. - -When conversion is enabled, #GstAudioAggregator will accept -any type of raw audio caps and perform conversion -on the data arriving on its sink pads, with whatever downstream -expects as the target format. - -In case downstream caps are not fully fixated, it will use -the first configured sink pad to finish fixating its source pad -caps. - -A notable exception for now is the sample rate, sink pads must -have the same sample rate as either the downstream requirement, -or the first configured pad, or a combination of both (when -downstream specifies a range or a set of acceptable rates). - -The #GstAggregator::samples-selected signal is provided with some -additional information about the output buffer: -- "offset" G_TYPE_UINT64 Offset in samples since segment start - for the position that is next to be filled in the output buffer. -- "frames" G_TYPE_UINT Number of frames per output buffer. - -In addition the gst_aggregator_peek_next_sample() function returns -additional information in the info #GstStructure of the returned sample: -- "output-offset" G_TYPE_UINT64 Sample offset in output segment relative to - the output segment's start where the current position of this input - buffer would be placed -- "position" G_TYPE_UINT current position in the input buffer in samples -- "size" G_TYPE_UINT size of the input buffer in samples - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Output block size in nanoseconds, expressed as a fraction. - - - - - - - The caps set by the subclass - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An implementation of GstPad that can be used with #GstAudioAggregator. - -See #GstAudioAggregator for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The default implementation of GstPad used with #GstAudioAggregator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The audio info for this pad set from the incoming caps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This is the base class for audio sinks. Subclasses need to implement the -::create_ringbuffer vmethod. This base class will then take care of -writing samples to the ringbuffer, synchronisation, clipping and flushing. - - - Create and return the #GstAudioRingBuffer for @sink. This function will -call the ::create_ringbuffer vmethod and will set @sink as the parent of -the returned buffer (see gst_object_set_parent()). - - - The new ringbuffer of @sink. - - - - - a #GstAudioBaseSink. - - - - - - - - - - - - - - - - - - - - Create and return the #GstAudioRingBuffer for @sink. This function will -call the ::create_ringbuffer vmethod and will set @sink as the parent of -the returned buffer (see gst_object_set_parent()). - - - The new ringbuffer of @sink. - - - - - a #GstAudioBaseSink. - - - - - - Get the current alignment threshold, in nanoseconds, used by @sink. - - - The current alignment threshold used by @sink. - - - - - a #GstAudioBaseSink - - - - - - Get the current discont wait, in nanoseconds, used by @sink. - - - The current discont wait used by @sink. - - - - - a #GstAudioBaseSink - - - - - - Get the current drift tolerance, in microseconds, used by @sink. - - - The current drift tolerance used by @sink. - - - - - a #GstAudioBaseSink - - - - - - Queries whether @sink will provide a clock or not. See also -gst_audio_base_sink_set_provide_clock. - - - %TRUE if @sink will provide a clock. - - - - - a #GstAudioBaseSink - - - - - - Get the current slave method used by @sink. - - - The current slave method used by @sink. - - - - - a #GstAudioBaseSink - - - - - - Informs this base class that the audio output device has failed for -some reason, causing a discontinuity (for example, because the device -recovered from the error, but lost all contents of its ring buffer). -This function is typically called by derived classes, and is useful -for the custom slave method. - - - - - - - a #GstAudioBaseSink - - - - - - Controls the sink's alignment threshold. - - - - - - - a #GstAudioBaseSink - - - - the new alignment threshold in nanoseconds - - - - - - Sets the custom slaving callback. This callback will -be invoked if the slave-method property is set to -GST_AUDIO_BASE_SINK_SLAVE_CUSTOM and the audio sink -receives and plays samples. - -Setting the callback to NULL causes the sink to -behave as if the GST_AUDIO_BASE_SINK_SLAVE_NONE -method were used. - - - - - - - a #GstAudioBaseSink - - - - a #GstAudioBaseSinkCustomSlavingCallback - - - - user data passed to the callback - - - - called when user_data becomes unused - - - - - - Controls how long the sink will wait before creating a discontinuity. - - - - - - - a #GstAudioBaseSink - - - - the new discont wait in nanoseconds - - - - - - Controls the sink's drift tolerance. - - - - - - - a #GstAudioBaseSink - - - - the new drift tolerance in microseconds - - - - - - Controls whether @sink will provide a clock or not. If @provide is %TRUE, -gst_element_provide_clock() will return a clock that reflects the datarate -of @sink. If @provide is %FALSE, gst_element_provide_clock() will return -NULL. - - - - - - - a #GstAudioBaseSink - - - - new state - - - - - - Controls how clock slaving will be performed in @sink. - - - - - - - a #GstAudioBaseSink - - - - the new slave method - - - - - - - - - - - - - - - A window of time in nanoseconds to wait before creating a discontinuity as -a result of breaching the drift-tolerance. - - - - Controls the amount of time in microseconds that clocks are allowed -to drift before resynchronisation happens. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioBaseSink class. Override the vmethod to implement -functionality. - - - the parent class. - - - - - - - The new ringbuffer of @sink. - - - - - a #GstAudioBaseSink. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function is set with gst_audio_base_sink_set_custom_slaving_callback() -and is called during playback. It receives the current time of external and -internal clocks, which the callback can then use to apply any custom -slaving/synchronization schemes. - -The external clock is the sink's element clock, the internal one is the -internal audio clock. The internal audio clock's calibration is applied to -the timestamps before they are passed to the callback. The difference between -etime and itime is the skew; how much internal and external clock lie apart -from each other. A skew of 0 means both clocks are perfectly in sync. -itime > etime means the external clock is going slower, while itime < etime -means it is going faster than the internal clock. etime and itime are always -valid timestamps, except for when a discontinuity happens. - -requested_skew is an output value the callback can write to. It informs the -sink of whether or not it should move the playout pointer, and if so, by how -much. This pointer is only NULL if a discontinuity occurs; otherwise, it is -safe to write to *requested_skew. The default skew is 0. - -The sink may experience discontinuities. If one happens, discont is TRUE, -itime, etime are set to GST_CLOCK_TIME_NONE, and requested_skew is NULL. -This makes it possible to reset custom clock slaving algorithms when a -discontinuity happens. - - - - - - - a #GstAudioBaseSink - - - - external clock time - - - - internal clock time - - - - skew amount requested by the callback - - - - reason for discontinuity (if any) - - - - user data - - - - - - Different possible reasons for discontinuities. This enum is useful for the custom -slave method. - - No discontinuity occurred - - - New caps are set, causing renegotiotion - - - Samples have been flushed - - - Sink was synchronized to the estimated latency (occurs during initialization) - - - Aligning buffers failed because the timestamps are too discontinuous - - - Audio output device experienced and recovered from an error but introduced latency in the process (see also @gst_audio_base_sink_report_device_failure()) - - - - - - - Different possible clock slaving algorithms used when the internal audio -clock is not selected as the pipeline master clock. - - Resample to match the master clock - - - Adjust playout pointer when master clock -drifts too much. - - - No adjustment is done. - - - Use custom clock slaving algorithm (Since: 1.6) - - - - This is the base class for audio sources. Subclasses need to implement the -::create_ringbuffer vmethod. This base class will then take care of -reading samples from the ringbuffer, synchronisation and flushing. - - - Create and return the #GstAudioRingBuffer for @src. This function will call -the ::create_ringbuffer vmethod and will set @src as the parent of the -returned buffer (see gst_object_set_parent()). - - - The new ringbuffer of @src. - - - - - a #GstAudioBaseSrc. - - - - - - Create and return the #GstAudioRingBuffer for @src. This function will call -the ::create_ringbuffer vmethod and will set @src as the parent of the -returned buffer (see gst_object_set_parent()). - - - The new ringbuffer of @src. - - - - - a #GstAudioBaseSrc. - - - - - - Queries whether @src will provide a clock or not. See also -gst_audio_base_src_set_provide_clock. - - - %TRUE if @src will provide a clock. - - - - - a #GstAudioBaseSrc - - - - - - Get the current slave method used by @src. - - - The current slave method used by @src. - - - - - a #GstAudioBaseSrc - - - - - - Controls whether @src will provide a clock or not. If @provide is %TRUE, -gst_element_provide_clock() will return a clock that reflects the datarate -of @src. If @provide is %FALSE, gst_element_provide_clock() will return NULL. - - - - - - - a #GstAudioBaseSrc - - - - new state - - - - - - Controls how clock slaving will be performed in @src. - - - - - - - a #GstAudioBaseSrc - - - - the new slave method - - - - - - Actual configured size of audio buffer in microseconds. - - - - Actual configured audio latency in microseconds. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioBaseSrc class. Override the vmethod to implement -functionality. - - - the parent class. - - - - - - - The new ringbuffer of @src. - - - - - a #GstAudioBaseSrc. - - - - - - - - - - - - - - - - Different possible clock slaving algorithms when the internal audio clock was -not selected as the pipeline clock. - - Resample to match the master clock. - - - Retimestamp output buffers with master -clock time. - - - Adjust capture pointer when master clock -drifts too much. - - - No adjustment is done. - - - - A structure containing the result of an audio buffer map operation, -which is executed with gst_audio_buffer_map(). For non-interleaved (planar) -buffers, the beginning of each channel in the buffer has its own pointer in -the @planes array. For interleaved buffers, the @planes array only contains -one item, which is the pointer to the beginning of the buffer, and @n_planes -equals 1. - -The different channels in @planes are always in the GStreamer channel order. - - - a #GstAudioInfo describing the audio properties of this buffer - - - - the size of the buffer in samples - - - - the number of planes available - - - - an array of @n_planes pointers pointing to the start of each - plane in the mapped buffer - - - - the mapped buffer - - - - - - - - - - - - - - - - - - - - - - Maps an audio @gstbuffer so that it can be read or written and stores the -result of the map operation in @buffer. - -This is especially useful when the @gstbuffer is in non-interleaved (planar) -layout, in which case this function will use the information in the -@gstbuffer's attached #GstAudioMeta in order to map each channel in a -separate "plane" in #GstAudioBuffer. If a #GstAudioMeta is not attached -on the @gstbuffer, then it must be in interleaved layout. - -If a #GstAudioMeta is attached, then the #GstAudioInfo on the meta is checked -against @info. Normally, they should be equal, but in case they are not, -a g_critical will be printed and the #GstAudioInfo from the meta will be -used. - -In non-interleaved buffers, it is possible to have each channel on a separate -#GstMemory. In this case, each memory will be mapped separately to avoid -copying their contents in a larger memory area. Do note though that it is -not supported to have a single channel spanning over two or more different -#GstMemory objects. Although the map operation will likely succeed in this -case, it will be highly sub-optimal and it is recommended to merge all the -memories in the buffer before calling this function. - -Note: The actual #GstBuffer is not ref'ed, but it is required to stay valid -as long as it's mapped. - - - %TRUE if the map operation succeeded or %FALSE on failure - - - - - pointer to a #GstAudioBuffer - - - - the audio properties of the buffer - - - - the #GstBuffer to be mapped - - - - the access mode for the memory - - - - - - Unmaps an audio buffer that was previously mapped with -gst_audio_buffer_map(). - - - - - - - the #GstAudioBuffer to unmap - - - - - - Clip the buffer to the given %GstSegment. - -After calling this function the caller does not own a reference to -@buffer anymore. - - - %NULL if the buffer is completely outside the configured segment, -otherwise the clipped buffer is returned. - -If the buffer has no timestamp, it is assumed to be inside the segment and -is not clipped - - - - - The buffer to clip. - - - - Segment in %GST_FORMAT_TIME or %GST_FORMAT_DEFAULT to which - the buffer should be clipped. - - - - sample rate. - - - - size of one audio frame in bytes. This is the size of one sample * -number of channels. - - - - - - Reorders @buffer from the channel positions @from to the channel -positions @to. @from and @to must contain the same number of -positions and the same positions, only in a different order. -@buffer must be writable. - - - %TRUE if the reordering was possible. - - - - - The buffer to reorder. - - - - The %GstAudioFormat of the buffer. - - - - The number of channels. - - - - The channel positions in the buffer. - - - - - - The channel positions to convert to. - - - - - - - - Truncate the buffer to finally have @samples number of samples, removing -the necessary amount of samples from the end and @trim number of samples -from the beginning. - -After calling this function the caller does not own a reference to -@buffer anymore. - - - the truncated buffer or %NULL if the arguments - were invalid - - - - - The buffer to truncate. - - - - size of one audio frame in bytes. This is the size of one sample * -number of channels. - - - - the number of samples to remove from the beginning of the buffer - - - - the final number of samples that should exist in this buffer or -1 -to use all the remaining samples if you are only removing samples from the -beginning. - - - - - - - Provides a base class for CD digital audio (CDDA) sources, which handles -things like seeking, querying, discid calculation, tags, and buffer -timestamping. - -## Using GstAudioCdSrc-based elements in applications - -GstAudioCdSrc registers two #GstFormat<!-- -->s of its own, namely -the "track" format and the "sector" format. Applications will usually -only find the "track" format interesting. You can retrieve that #GstFormat -for use in seek events or queries with gst_format_get_by_nick("track"). - -In order to query the number of tracks, for example, an application would -set the CDDA source element to READY or PAUSED state and then query the -the number of tracks via gst_element_query_duration() using the track -format acquired above. Applications can query the currently playing track -in the same way. - -Alternatively, applications may retrieve the currently playing track and -the total number of tracks from the taglist that will posted on the bus -whenever the CD is opened or the currently playing track changes. The -taglist will contain GST_TAG_TRACK_NUMBER and GST_TAG_TRACK_COUNT tags. - -Applications playing back CD audio using playbin and cdda://n URIs should -issue a seek command in track format to change between tracks, rather than -setting a new cdda://n+1 URI on playbin (as setting a new URI on playbin -involves closing and re-opening the CD device, which is much much slower). - -## Tags and meta-information - -CDDA sources will automatically emit a number of tags, details about which -can be found in the libgsttag documentation. Those tags are: -#GST_TAG_CDDA_CDDB_DISCID, #GST_TAG_CDDA_CDDB_DISCID_FULL, -#GST_TAG_CDDA_MUSICBRAINZ_DISCID, #GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL, -among others. - -## Tracks and Table of Contents (TOC) - -Applications will be informed of the available tracks via a TOC message -on the pipeline's #GstBus. The #GstToc will contain a #GstTocEntry for -each track, with information about each track. The duration for each -track can be retrieved via the #GST_TAG_DURATION tag from each entry's -tag list, or calculated via gst_toc_entry_get_start_stop_times(). -The track entries in the TOC will be sorted by track number. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CDDA sources use this function from their start vfunc to announce the -available data and audio tracks to the base source class. The caller -should allocate @track on the stack, the base source will do a shallow -copy of the structure (and take ownership of the taglist if there is one). - - - FALSE on error, otherwise TRUE. - - - - - a #GstAudioCdSrc - - - - address of #GstAudioCdSrcTrack to add - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Audio CD source base class. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Mode in which the CD audio source operates. Influences timestamping, -EOS handling and seeking. - - each single track is a stream - - - the entire disc is a single stream - - - - - - - CD track abstraction to communicate TOC entries to the base class. - -This structure is only for use by sub-classed in connection with -gst_audio_cd_src_add_track(). - -Applications will be informed of the available tracks via a TOC message -on the pipeline's #GstBus instead. - - - Whether this is an audio track - - - - Track number in TOC (usually starts from 1, but not always) - - - - The first sector of this track (LBA) - - - - The last sector of this track (LBA) - - - - Track-specific tags (e.g. from cd-text information), or NULL - - - - - - - - - - - - - - - - - Free memory allocated by @mix. - - - - - - - a #GstAudioChannelMixer - - - - - - Check if @mix is in passthrough. - -Only N x N mix identity matrices are considered passthrough, -this is determined by comparing the contents of the matrix -with 0.0 and 1.0. - -As this is floating point comparisons, if the values have been -generated, they should be rounded up or down by explicit -assignment of 0.0 or 1.0 to values within a user-defined -epsilon, this code doesn't make assumptions as to what may -constitute an appropriate epsilon. - - - %TRUE is @mix is passthrough. - - - - - a #GstAudioChannelMixer - - - - - - In case the samples are interleaved, @in and @out must point to an -array with a single element pointing to a block of interleaved samples. - -If non-interleaved samples are used, @in and @out must point to an -array with pointers to memory blocks, one for each channel. - -Perform channel mixing on @in_data and write the result to @out_data. -@in_data and @out_data need to be in @format and @layout. - - - - - - - a #GstAudioChannelMixer - - - - input samples - - - - output samples - - - - number of samples - - - - - - Create a new channel mixer object for the given parameters. - - - a new #GstAudioChannelMixer object, or %NULL if @format isn't supported. - Free with gst_audio_channel_mixer_free() after usage. - - - - - #GstAudioChannelMixerFlags - - - - - - - number of input channels - - - - positions of input channels - - - - number of output channels - - - - positions of output channels - - - - - - Create a new channel mixer object for the given parameters. - - - a new #GstAudioChannelMixer object, or %NULL if @format isn't supported, - @matrix is invalid, or @matrix is %NULL and @in_channels != @out_channels. - Free with gst_audio_channel_mixer_free() after usage. - - - - - #GstAudioChannelMixerFlags - - - - - - - number of input channels - - - - number of output channels - - - - channel conversion matrix, m[@in_channels][@out_channels]. - If identity matrix, passthrough applies. If %NULL, a (potentially truncated) - identity matrix is generated. - - - - - - - Flags passed to gst_audio_channel_mixer_new() - - no flag - - - input channels are not interleaved - - - output channels are not interleaved - - - input channels are explicitly unpositioned - - - output channels are explicitly unpositioned - - - - Audio channel positions. - -These are the channels defined in SMPTE 2036-2-2008 -Table 1 for 22.2 audio systems with the Surround and Wide channels from -DTS Coherent Acoustics (v.1.3.1) and 10.2 and 7.1 layouts. In the caps the -actual channel layout is expressed with a channel count and a channel mask, -which describes the existing channels. The positions in the bit mask correspond -to the enum values. -For negotiation it is allowed to have more bits set in the channel mask than -the number of channels to specify the allowed channel positions but this is -not allowed in negotiated caps. It is not allowed in any situation other -than the one mentioned below to have less bits set in the channel mask than -the number of channels. - -@GST_AUDIO_CHANNEL_POSITION_MONO can only be used with a single mono channel that -has no direction information and would be mixed into all directional channels. -This is expressed in caps by having a single channel and no channel mask. - -@GST_AUDIO_CHANNEL_POSITION_NONE can only be used if all channels have this position. -This is expressed in caps by having a channel mask with no bits set. - -As another special case it is allowed to have two channels without a channel mask. -This implicitly means that this is a stereo stream with a front left and front right -channel. - - used for position-less channels, e.g. - from a sound card that records 1024 channels; mutually exclusive with - any other channel position - - - Mono without direction; - can only be used with 1 channel - - - invalid position - - - Front left - - - Front right - - - Front center - - - Low-frequency effects 1 (subwoofer) - - - Rear left - - - Rear right - - - Front left of center - - - Front right of center - - - Rear center - - - Low-frequency effects 2 (subwoofer) - - - Side left - - - Side right - - - Top front left - - - Top front right - - - Top front center - - - Top center - - - Top rear left - - - Top rear right - - - Top side right - - - Top rear right - - - Top rear center - - - Bottom front center - - - Bottom front left - - - Bottom front right - - - Wide left (between front left and side left) - - - Wide right (between front right and side right) - - - Surround left (between rear left and side left) - - - Surround right (between rear right and side right) - - - - Extra buffer metadata describing how much audio has to be clipped from -the start or end of a buffer. This is used for compressed formats, where -the first frame usually has some additional samples due to encoder and -decoder delays, and the last frame usually has some additional samples to -be able to fill the complete last frame. - -This is used to ensure that decoded data in the end has the same amount of -samples, and multiply decoded streams can be gaplessly concatenated. - -Note: If clipping of the start is done by adjusting the segment, this meta -has to be dropped from buffers as otherwise clipping could happen twice. - - - parent #GstMeta - - - - GstFormat of @start and @stop, GST_FORMAT_DEFAULT is samples - - - - Amount of audio to clip from start of buffer - - - - Amount of to clip from end of buffer - - - - - - - - - - - #GstAudioClock makes it easy for elements to implement a #GstClock, they -simply need to provide a function that returns the current clock time. - -This object is internally used to implement the clock in #GstAudioBaseSink. - - - Create a new #GstAudioClock instance. Whenever the clock time should be -calculated it will call @func with @user_data. When @func returns -#GST_CLOCK_TIME_NONE, the clock will return the last reported time. - - - a new #GstAudioClock casted to a #GstClock. - - - - - the name of the clock - - - - a function - - - - user data - - - - #GDestroyNotify for @user_data - - - - - - Adjust @time with the internal offset of the audio clock. - - - @time adjusted with the internal offset. - - - - - a #GstAudioClock - - - - a #GstClockTime - - - - - - Report the time as returned by the #GstAudioClockGetTimeFunc without applying -any offsets. - - - the time as reported by the time function of the audio clock - - - - - a #GstAudioClock - - - - - - Invalidate the clock function. Call this function when the provided -#GstAudioClockGetTimeFunc cannot be called anymore, for example, when the -user_data becomes invalid. - -After calling this function, @clock will return the last returned time for -the rest of its lifetime. - - - - - - - a #GstAudioClock - - - - - - Inform @clock that future calls to #GstAudioClockGetTimeFunc will return values -starting from @time. The clock will update an internal offset to make sure that -future calls to internal_time will return an increasing result as required by -the #GstClock object. - - - - - - - a #GstAudioClock - - - - a #GstClockTime - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function will be called whenever the current clock time needs to be -calculated. If this function returns #GST_CLOCK_TIME_NONE, the last reported -time will be returned by the clock. - - - the current time or #GST_CLOCK_TIME_NONE if the previous time should -be used. - - - - - the #GstAudioClock - - - - user data - - - - - - This object is used to convert audio samples from one format to another. -The object can perform conversion of: - - * audio format with optional dithering and noise shaping - - * audio samplerate - - * audio channels and channel layout - - - Create a new #GstAudioConverter that is able to convert between @in and @out -audio formats. - -@config contains extra configuration options, see `GST_AUDIO_CONVERTER_OPT_*` -parameters for details about the options and values. - - - a #GstAudioConverter or %NULL if conversion is not possible. - - - - - extra #GstAudioConverterFlags - - - - a source #GstAudioInfo - - - - a destination #GstAudioInfo - - - - a #GstStructure with configuration options - - - - - - Convenience wrapper around gst_audio_converter_samples(), which will -perform allocation of the output buffer based on the result from -gst_audio_converter_get_out_frames(). - - - %TRUE is the conversion could be performed. - - - - - a #GstAudioConverter - - - - extra #GstAudioConverterFlags - - - - input data - - - - - - size of @in - - - - a pointer where - the output data will be written - - - - - - a pointer where the size of @out will be written - - - - - - Free a previously allocated @convert instance. - - - - - - - a #GstAudioConverter - - - - - - Get the current configuration of @convert. - - - - a #GstStructure that remains valid for as long as @convert is valid - or until gst_audio_converter_update_config() is called. - - - - - a #GstAudioConverter - - - - result input rate - - - - result output rate - - - - - - Calculate how many input frames are currently needed by @convert to produce -@out_frames of output frames. - - - the number of input frames - - - - - a #GstAudioConverter - - - - number of output frames - - - - - - Get the maximum number of input frames that the converter would -need before producing output. - - - the latency of @convert as expressed in the number of -frames. - - - - - a #GstAudioConverter - - - - - - Calculate how many output frames can be produced when @in_frames input -frames are given to @convert. - - - the number of output frames - - - - - a #GstAudioConverter - - - - number of input frames - - - - - - Returns whether the audio converter will operate in passthrough mode. -The return value would be typically input to gst_base_transform_set_passthrough() - - - %TRUE when no conversion will actually occur. - - - - - - - - - - Reset @convert to the state it was when it was first created, clearing -any history it might currently have. - - - - - - - a #GstAudioConverter - - - - - - Perform the conversion with @in_frames in @in to @out_frames in @out -using @convert. - -In case the samples are interleaved, @in and @out must point to an -array with a single element pointing to a block of interleaved samples. - -If non-interleaved samples are used, @in and @out must point to an -array with pointers to memory blocks, one for each channel. - -@in may be %NULL, in which case @in_frames of silence samples are processed -by the converter. - -This function always produces @out_frames of output and consumes @in_frames of -input. Use gst_audio_converter_get_out_frames() and -gst_audio_converter_get_in_frames() to make sure @in_frames and @out_frames -are matching and @in and @out point to enough memory. - - - %TRUE is the conversion could be performed. - - - - - a #GstAudioConverter - - - - extra #GstAudioConverterFlags - - - - input frames - - - - number of input frames - - - - output frames - - - - number of output frames - - - - - - Returns whether the audio converter can perform the conversion in-place. -The return value would be typically input to gst_base_transform_set_in_place() - - - %TRUE when the conversion can be done in place. - - - - - a #GstAudioConverter - - - - - - Set @in_rate, @out_rate and @config as extra configuration for @convert. - -@in_rate and @out_rate specify the new sample rates of input and output -formats. A value of 0 leaves the sample rate unchanged. - -@config can be %NULL, in which case, the current configuration is not -changed. - -If the parameters in @config can not be set exactly, this function returns -%FALSE and will try to update as much state as possible. The new state can -then be retrieved and refined with gst_audio_converter_get_config(). - -Look at the `GST_AUDIO_CONVERTER_OPT_*` fields to check valid configuration -option and values. - - - %TRUE when the new parameters could be set - - - - - a #GstAudioConverter - - - - input rate - - - - output rate - - - - a #GstStructure or %NULL - - - - - - - Extra flags passed to gst_audio_converter_new() and gst_audio_converter_samples(). - - no flag - - - the input sample arrays are writable and can be - used as temporary storage during conversion. - - - allow arbitrary rate updates with - gst_audio_converter_update_config(). - - - - This base class is for audio decoders turning encoded data into -raw audio samples. - -GstAudioDecoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstAudioDecoder calls @start when the decoder element - is activated, which allows subclass to perform any global setup. - Base class (context) parameters can already be set according to subclass - capabilities (or possibly upon receive more information in subsequent - @set_format). - * GstAudioDecoder calls @set_format to inform subclass of the format - of input audio data that it is about to receive. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - * GstAudioDecoder calls @stop at end of all processing. - -As of configuration stage, and throughout processing, GstAudioDecoder -provides various (context) parameters, e.g. describing the format of -output audio data (valid when output caps have been set) or current parsing state. -Conversely, subclass can and should configure context to inform -base class of its expectation w.r.t. buffer handling. - -## Data processing - * Base class gathers input data, and optionally allows subclass - to parse this into subsequently manageable (as defined by subclass) - chunks. Such chunks are subsequently referred to as 'frames', - though they may or may not correspond to 1 (or more) audio format frame. - * Input frame is provided to subclass' @handle_frame. - * If codec processing results in decoded data, subclass should call - @gst_audio_decoder_finish_frame to have decoded data pushed - downstream. - * Just prior to actually pushing a buffer downstream, - it is passed to @pre_push. Subclass should either use this callback - to arrange for additional downstream pushing or otherwise ensure such - custom pushing occurs after at least a method call has finished since - setting src pad caps. - * During the parsing process GstAudioDecoderClass will handle both - srcpad and sinkpad events. Sink events will be passed to subclass - if @event callback has been provided. - -## Shutdown phase - - * GstAudioDecoder class calls @stop to inform the subclass that data - parsing will be stopped. - -Subclass is responsible for providing pad template caps for -source and sink pads. The pads need to be named "sink" and "src". It also -needs to set the fixed caps on srcpad, when the format is ensured. This -is typically when base class calls subclass' @set_format function, though -it might be delayed until calling @gst_audio_decoder_finish_frame. - -In summary, above process should have subclass concentrating on -codec data processing while leaving other matters to base class, -such as most notably timestamp handling. While it may exert more control -in this area (see e.g. @pre_push), it is very much not recommended. - -In particular, base class will try to arrange for perfect output timestamps -as much as possible while tracking upstream timestamps. -To this end, if deviation between the next ideal expected perfect timestamp -and upstream exceeds #GstAudioDecoder:tolerance, then resync to upstream -occurs (which would happen always if the tolerance mechanism is disabled). - -In non-live pipelines, baseclass can also (configurably) arrange for -output buffer aggregation which may help to redue large(r) numbers of -small(er) buffers being pushed and processed downstream. Note that this -feature is only available if the buffer layout is interleaved. For planar -buffers, the decoder implementation is fully responsible for the output -buffer size. - -On the other hand, it should be noted that baseclass only provides limited -seeking support (upon explicit subclass request), as full-fledged support -should rather be left to upstream demuxer, parser or alike. This simple -approach caters for seeking and duration reporting using estimated input -bitrates. - -Things that subclass need to take care of: - - * Provide pad templates - * Set source pad caps when appropriate - * Set user-configurable properties to sane defaults for format and - implementing codec at hand, and convey some subclass capabilities and - expectations in context. - - * Accept data in @handle_frame and provide encoded results to - @gst_audio_decoder_finish_frame. If it is prepared to perform - PLC, it should also accept NULL data in @handle_frame and provide for - data for indicated duration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiate with downstream elements to currently configured #GstAudioInfo. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioDecoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Helper function that allocates a buffer to hold an audio frame -for @dec's current output format. - - - allocated buffer - - - - - a #GstAudioDecoder - - - - size of the buffer - - - - - - Collects decoded data and pushes it downstream. - -@buf may be NULL in which case the indicated number of frames -are discarded and considered to have produced no output -(e.g. lead-in or setup frames). -Otherwise, source pad caps must be set when it is called with valid -data in @buf. - -Note that a frame received in #GstAudioDecoderClass.handle_frame() may be -invalidated by a call to this function. - - - a #GstFlowReturn that should be escalated to caller (of caller) - - - - - a #GstAudioDecoder - - - - decoded data - - - - number of decoded frames represented by decoded data - - - - - - Collects decoded data and pushes it downstream. This function may be called -multiple times for a given input frame. - -@buf may be NULL in which case it is assumed that the current input frame is -finished. This is equivalent to calling gst_audio_decoder_finish_subframe() -with a NULL buffer and frames=1 after having pushed out all decoded audio -subframes using this function. - -When called with valid data in @buf the source pad caps must have been set -already. - -Note that a frame received in #GstAudioDecoderClass.handle_frame() may be -invalidated by a call to this function. - - - a #GstFlowReturn that should be escalated to caller (of caller) - - - - - a #GstAudioDecoder - - - - decoded data - - - - - - Lets #GstAudioDecoder sub-classes to know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after use it. - - - - - - - a #GstAudioDecoder - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - - - a #GstAudioInfo describing the input audio format - - - - - a #GstAudioDecoder - - - - - - - - currently configured decoder delay - - - - - a #GstAudioDecoder - - - - - - Queries decoder drain handling. - - - TRUE if drainable handling is enabled. - -MT safe. - - - - - a #GstAudioDecoder - - - - - - - - currently configured byte to time conversion setting - - - - - a #GstAudioDecoder - - - - - - Sets the variables pointed to by @min and @max to the currently configured -latency. - - - - - - - a #GstAudioDecoder - - - - a pointer to storage to hold minimum latency - - - - a pointer to storage to hold maximum latency - - - - - - - - currently configured decoder tolerated error count. - - - - - a #GstAudioDecoder - - - - - - Queries decoder's latency aggregation. - - - aggregation latency. - -MT safe. - - - - - a #GstAudioDecoder - - - - - - Queries decoder required format handling. - - - TRUE if required format handling is enabled. - -MT safe. - - - - - a #GstAudioDecoder - - - - - - Return current parsing (sync and eos) state. - - - - - - - a #GstAudioDecoder - - - - a pointer to a variable to hold the current sync state - - - - a pointer to a variable to hold the current eos state - - - - - - Queries decoder packet loss concealment handling. - - - TRUE if packet loss concealment is enabled. - -MT safe. - - - - - a #GstAudioDecoder - - - - - - - - currently configured plc handling - - - - - a #GstAudioDecoder - - - - - - Queries current audio jitter tolerance threshold. - - - decoder audio jitter tolerance threshold. - -MT safe. - - - - - a #GstAudioDecoder - - - - - - Sets the audio decoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with gst_audio_decoder_merge_tags(). - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - - - - - - - a #GstAudioDecoder - - - - a #GstTagList to merge, or NULL - - - - the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE - - - - - - Negotiate with downstream elements to currently configured #GstAudioInfo. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioDecoder - - - - - - Returns caps that express @caps (or sink template caps if @caps == NULL) -restricted to rate/channels/... combinations supported by downstream -elements. - - - a #GstCaps owned by caller - - - - - a #GstAudioDecoder - - - - initial caps - - - - filter caps - - - - - - Sets a caps in allocation query which are different from the set -pad's caps. Use this function before calling -gst_audio_decoder_negotiate(). Setting to %NULL the allocation -query will use the caps from the pad. - - - - - - - a #GstAudioDecoder - - - - a #GstCaps or %NULL - - - - - - Configures decoder drain handling. If drainable, subclass might -be handed a NULL buffer to have it return any leftover decoded data. -Otherwise, it is not considered so capable and will only ever be passed -real data. - -MT safe. - - - - - - - a #GstAudioDecoder - - - - new state - - - - - - Allows baseclass to perform byte to time estimated conversion. - - - - - - - a #GstAudioDecoder - - - - whether to enable byte to time conversion - - - - - - Sets decoder latency. - - - - - - - a #GstAudioDecoder - - - - minimum latency - - - - maximum latency - - - - - - Sets numbers of tolerated decoder errors, where a tolerated one is then only -warned about, but more than tolerated will lead to fatal error. You can set --1 for never returning fatal errors. Default is set to -GST_AUDIO_DECODER_MAX_ERRORS. - - - - - - - a #GstAudioDecoder - - - - max tolerated errors - - - - - - Sets decoder minimum aggregation latency. - -MT safe. - - - - - - - a #GstAudioDecoder - - - - new minimum latency - - - - - - Configures decoder format needs. If enabled, subclass needs to be -negotiated with format caps before it can process any data. It will then -never be handed any data before it has been configured. -Otherwise, it might be handed data without having been configured and -is then expected being able to do so either by default -or based on the input data. - -MT safe. - - - - - - - a #GstAudioDecoder - - - - new state - - - - - - Configure output caps on the srcpad of @dec. Similar to -gst_audio_decoder_set_output_format(), but allows subclasses to specify -output caps that can't be expressed via #GstAudioInfo e.g. caps that have -caps features. - - - %TRUE on success. - - - - - a #GstAudioDecoder - - - - (fixed) #GstCaps - - - - - - Configure output info on the srcpad of @dec. - - - %TRUE on success. - - - - - a #GstAudioDecoder - - - - #GstAudioInfo - - - - - - Enable or disable decoder packet loss concealment, provided subclass -and codec are capable and allow handling plc. - -MT safe. - - - - - - - a #GstAudioDecoder - - - - new state - - - - - - Indicates whether or not subclass handles packet loss concealment (plc). - - - - - - - a #GstAudioDecoder - - - - new plc state - - - - - - Configures decoder audio jitter tolerance threshold. - -MT safe. - - - - - - - a #GstAudioDecoder - - - - new tolerance - - - - - - Lets #GstAudioDecoder sub-classes decide if they want the sink pad -to use the default pad query handler to reply to accept-caps queries. - -By setting this to true it is possible to further customize the default -handler with %GST_PAD_SET_ACCEPT_INTERSECT and -%GST_PAD_SET_ACCEPT_TEMPLATE - - - - - - - a #GstAudioDecoder - - - - if the default pad accept-caps query handling should be used - - - - - - Maximum number of tolerated consecutive decode errors. See -gst_audio_decoder_set_max_errors() for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum @handle_frame (and likely @set_format) needs to be -overridden. - - - The parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioDecoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Set of available dithering methods. - - No dithering - - - Rectangular dithering - - - Triangular dithering (default) - - - High frequency triangular dithering - - - - Extra buffer metadata describing audio downmixing matrix. This metadata is -attached to audio buffers and contains a matrix to downmix the buffer number -of channels to @channels. - -@matrix is an two-dimensional array of @to_channels times @from_channels -coefficients, i.e. the i-th output channels is constructed by multiplicating -the input channels with the coefficients in @matrix[i] and taking the sum -of the results. - - - parent #GstMeta - - - - the channel positions of the source - - - - the channel positions of the destination - - - - the number of channels of the source - - - - the number of channels of the destination - - - - the matrix coefficients. - - - - - - - - - - - This base class is for audio encoders turning raw audio samples into -encoded audio data. - -GstAudioEncoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstAudioEncoder calls @start when the encoder element - is activated, which allows subclass to perform any global setup. - - * GstAudioEncoder calls @set_format to inform subclass of the format - of input audio data that it is about to receive. Subclass should - setup for encoding and configure various base class parameters - appropriately, notably those directing desired input data handling. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - - * GstAudioEncoder calls @stop at end of all processing. - -As of configuration stage, and throughout processing, GstAudioEncoder -maintains various parameters that provide required context, -e.g. describing the format of input audio data. -Conversely, subclass can and should configure these context parameters -to inform base class of its expectation w.r.t. buffer handling. - -## Data processing - - * Base class gathers input sample data (as directed by the context's - frame_samples and frame_max) and provides this to subclass' @handle_frame. - * If codec processing results in encoded data, subclass should call - gst_audio_encoder_finish_frame() to have encoded data pushed - downstream. Alternatively, it might also call - gst_audio_encoder_finish_frame() (with a NULL buffer and some number of - dropped samples) to indicate dropped (non-encoded) samples. - * Just prior to actually pushing a buffer downstream, - it is passed to @pre_push. - * During the parsing process GstAudioEncoderClass will handle both - srcpad and sinkpad events. Sink events will be passed to subclass - if @event callback has been provided. - -## Shutdown phase - - * GstAudioEncoder class calls @stop to inform the subclass that data - parsing will be stopped. - -Subclass is responsible for providing pad template caps for -source and sink pads. The pads need to be named "sink" and "src". It also -needs to set the fixed caps on srcpad, when the format is ensured. This -is typically when base class calls subclass' @set_format function, though -it might be delayed until calling @gst_audio_encoder_finish_frame. - -In summary, above process should have subclass concentrating on -codec data processing while leaving other matters to base class, -such as most notably timestamp handling. While it may exert more control -in this area (see e.g. @pre_push), it is very much not recommended. - -In particular, base class will either favor tracking upstream timestamps -(at the possible expense of jitter) or aim to arrange for a perfect stream of -output timestamps, depending on #GstAudioEncoder:perfect-timestamp. -However, in the latter case, the input may not be so perfect or ideal, which -is handled as follows. An input timestamp is compared with the expected -timestamp as dictated by input sample stream and if the deviation is less -than #GstAudioEncoder:tolerance, the deviation is discarded. -Otherwise, it is considered a discontuinity and subsequent output timestamp -is resynced to the new position after performing configured discontinuity -processing. In the non-perfect-timestamp case, an upstream variation -exceeding tolerance only leads to marking DISCONT on subsequent outgoing -(while timestamps are adjusted to upstream regardless of variation). -While DISCONT is also marked in the perfect-timestamp case, this one -optionally (see #GstAudioEncoder:hard-resync) -performs some additional steps, such as clipping of (early) input samples -or draining all currently remaining input data, depending on the direction -of the discontuinity. - -If perfect timestamps are arranged, it is also possible to request baseclass -(usually set by subclass) to provide additional buffer metadata (in OFFSET -and OFFSET_END) fields according to granule defined semantics currently -needed by oggmux. Specifically, OFFSET is set to granulepos (= sample count -including buffer) and OFFSET_END to corresponding timestamp (as determined -by same sample count and sample rate). - -Things that subclass need to take care of: - - * Provide pad templates - * Set source pad caps when appropriate - * Inform base class of buffer processing needs using context's - frame_samples and frame_bytes. - * Set user-configurable properties to sane defaults for format and - implementing codec at hand, e.g. those controlling timestamp behaviour - and discontinuity processing. - * Accept data in @handle_frame and provide encoded results to - gst_audio_encoder_finish_frame(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiate with downstream elements to currently configured #GstCaps. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioEncoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Helper function that allocates a buffer to hold an encoded audio frame -for @enc's current output format. - - - allocated buffer - - - - - a #GstAudioEncoder - - - - size of the buffer - - - - - - Collects encoded data and pushes encoded data downstream. -Source pad caps must be set when this is called. - -If @samples < 0, then best estimate is all samples provided to encoder -(subclass) so far. @buf may be NULL, in which case next number of @samples -are considered discarded, e.g. as a result of discontinuous transmission, -and a discontinuity is marked. - -Note that samples received in #GstAudioEncoderClass.handle_frame() -may be invalidated by a call to this function. - - - a #GstFlowReturn that should be escalated to caller (of caller) - - - - - a #GstAudioEncoder - - - - encoded data - - - - number of samples (per channel) represented by encoded data - - - - - - Lets #GstAudioEncoder sub-classes to know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after use it. - - - - - - - a #GstAudioEncoder - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - - - a #GstAudioInfo describing the input audio format - - - - - a #GstAudioEncoder - - - - - - Queries encoder drain handling. - - - TRUE if drainable handling is enabled. - -MT safe. - - - - - a #GstAudioEncoder - - - - - - - - currently configured maximum handled frames - - - - - a #GstAudioEncoder - - - - - - - - currently maximum requested samples per frame - - - - - a #GstAudioEncoder - - - - - - - - currently minimum requested samples per frame - - - - - a #GstAudioEncoder - - - - - - Queries encoder hard minimum handling. - - - TRUE if hard minimum handling is enabled. - -MT safe. - - - - - a #GstAudioEncoder - - - - - - - - - - - - - - - - - Sets the variables pointed to by @min and @max to the currently configured -latency. - - - - - - - a #GstAudioEncoder - - - - a pointer to storage to hold minimum latency - - - - a pointer to storage to hold maximum latency - - - - - - - - currently configured encoder lookahead - - - - - a #GstAudioEncoder - - - - - - Queries if the encoder will handle granule marking. - - - TRUE if granule marking is enabled. - -MT safe. - - - - - a #GstAudioEncoder - - - - - - Queries encoder perfect timestamp behaviour. - - - TRUE if perfect timestamp setting enabled. - -MT safe. - - - - - a #GstAudioEncoder - - - - - - Queries current audio jitter tolerance threshold. - - - encoder audio jitter tolerance threshold. - -MT safe. - - - - - a #GstAudioEncoder - - - - - - Sets the audio encoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with gst_audio_encoder_merge_tags(). - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - a #GstTagList to merge, or NULL to unset - previously-set tags - - - - the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE - - - - - - Negotiate with downstream elements to currently configured #GstCaps. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioEncoder - - - - - - Returns caps that express @caps (or sink template caps if @caps == NULL) -restricted to channel/rate combinations supported by downstream elements -(e.g. muxers). - - - a #GstCaps owned by caller - - - - - a #GstAudioEncoder - - - - initial caps - - - - filter caps - - - - - - Sets a caps in allocation query which are different from the set -pad's caps. Use this function before calling -gst_audio_encoder_negotiate(). Setting to %NULL the allocation -query will use the caps from the pad. - - - - - - - a #GstAudioEncoder - - - - a #GstCaps or %NULL - - - - - - Configures encoder drain handling. If drainable, subclass might -be handed a NULL buffer to have it return any leftover encoded data. -Otherwise, it is not considered so capable and will only ever be passed -real data. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - new state - - - - - - Sets max number of frames accepted at once (assumed minimally 1). -Requires @frame_samples_min and @frame_samples_max to be the equal. - -Note: This value will be reset to 0 every time before -#GstAudioEncoderClass.set_format() is called. - - - - - - - a #GstAudioEncoder - - - - number of frames - - - - - - Sets number of samples (per channel) subclass needs to be handed, -at most or will be handed all available if 0. - -If an exact number of samples is required, gst_audio_encoder_set_frame_samples_min() -must be called with the same number. - -Note: This value will be reset to 0 every time before -#GstAudioEncoderClass.set_format() is called. - - - - - - - a #GstAudioEncoder - - - - number of samples per frame - - - - - - Sets number of samples (per channel) subclass needs to be handed, -at least or will be handed all available if 0. - -If an exact number of samples is required, gst_audio_encoder_set_frame_samples_max() -must be called with the same number. - -Note: This value will be reset to 0 every time before -#GstAudioEncoderClass.set_format() is called. - - - - - - - a #GstAudioEncoder - - - - number of samples per frame - - - - - - Configures encoder hard minimum handling. If enabled, subclass -will never be handed less samples than it configured, which otherwise -might occur near end-of-data handling. Instead, the leftover samples -will simply be discarded. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - new state - - - - - - - - - - - - - - - - - - - - Set the codec headers to be sent downstream whenever requested. - - - - - - - a #GstAudioEncoder - - - - a list of - #GstBuffer containing the codec header - - - - - - - - Sets encoder latency. - - - - - - - a #GstAudioEncoder - - - - minimum latency - - - - maximum latency - - - - - - Sets encoder lookahead (in units of input rate samples) - -Note: This value will be reset to 0 every time before -#GstAudioEncoderClass.set_format() is called. - - - - - - - a #GstAudioEncoder - - - - lookahead - - - - - - Enable or disable encoder granule handling. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - new state - - - - - - Configure output caps on the srcpad of @enc. - - - %TRUE on success. - - - - - a #GstAudioEncoder - - - - #GstCaps - - - - - - Enable or disable encoder perfect output timestamp preference. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - new state - - - - - - Configures encoder audio jitter tolerance threshold. - -MT safe. - - - - - - - a #GstAudioEncoder - - - - new tolerance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum @set_format and @handle_frame needs to be overridden. - - - The parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAudioEncoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioFilter is a #GstBaseTransform<!-- -->-derived base class for simple audio -filters, ie. those that output the same format that they get as input. - -#GstAudioFilter will parse the input format for you (with error checking) -before calling your setup function. Also, elements deriving from -#GstAudioFilter may use gst_audio_filter_class_add_pad_templates() from -their class_init function to easily configure the set of caps/formats that -the element is able to handle. - -Derived classes should override the #GstAudioFilterClass.setup() and -#GstBaseTransformClass.transform_ip() and/or -#GstBaseTransformClass.transform() -virtual functions in their class_init function. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - In addition to the @setup virtual function, you should also override the -GstBaseTransform::transform and/or GstBaseTransform::transform_ip virtual -function. - - - parent class - - - - - - - - - - - - - - - - - - - - - - - - - Convenience function to add pad templates to this element class, with -@allowed_caps as the caps that can be handled. - -This function is usually used from within a GObject class_init function. - - - - - - - an #GstAudioFilterClass - - - - what formats the filter can handle, as #GstCaps - - - - - - - Extra audio flags - - no valid flag - - - the position array explicitly - contains unpositioned channels. - - - - Enum value describing the most common audio formats. - - unknown or unset audio format - - - encoded audio format - - - 8 bits in 8 bits, signed - - - 8 bits in 8 bits, unsigned - - - 16 bits in 16 bits, signed, little endian - - - 16 bits in 16 bits, signed, big endian - - - 16 bits in 16 bits, unsigned, little endian - - - 16 bits in 16 bits, unsigned, big endian - - - 24 bits in 32 bits, signed, little endian - - - 24 bits in 32 bits, signed, big endian - - - 24 bits in 32 bits, unsigned, little endian - - - 24 bits in 32 bits, unsigned, big endian - - - 32 bits in 32 bits, signed, little endian - - - 32 bits in 32 bits, signed, big endian - - - 32 bits in 32 bits, unsigned, little endian - - - 32 bits in 32 bits, unsigned, big endian - - - 24 bits in 24 bits, signed, little endian - - - 24 bits in 24 bits, signed, big endian - - - 24 bits in 24 bits, unsigned, little endian - - - 24 bits in 24 bits, unsigned, big endian - - - 20 bits in 24 bits, signed, little endian - - - 20 bits in 24 bits, signed, big endian - - - 20 bits in 24 bits, unsigned, little endian - - - 20 bits in 24 bits, unsigned, big endian - - - 18 bits in 24 bits, signed, little endian - - - 18 bits in 24 bits, signed, big endian - - - 18 bits in 24 bits, unsigned, little endian - - - 18 bits in 24 bits, unsigned, big endian - - - 32-bit floating point samples, little endian - - - 32-bit floating point samples, big endian - - - 64-bit floating point samples, little endian - - - 64-bit floating point samples, big endian - - - 16 bits in 16 bits, signed, native endianness - - - 16 bits in 16 bits, unsigned, native endianness - - - 24 bits in 32 bits, signed, native endianness - - - 24 bits in 32 bits, unsigned, native endianness - - - 32 bits in 32 bits, signed, native endianness - - - 32 bits in 32 bits, unsigned, native endianness - - - 24 bits in 24 bits, signed, native endianness - - - 24 bits in 24 bits, unsigned, native endianness - - - 20 bits in 24 bits, signed, native endianness - - - 20 bits in 24 bits, unsigned, native endianness - - - 18 bits in 24 bits, signed, native endianness - - - 18 bits in 24 bits, unsigned, native endianness - - - 32-bit floating point samples, native endianness - - - 64-bit floating point samples, native endianness - - - Construct a #GstAudioFormat with given parameters. - - - a #GstAudioFormat or GST_AUDIO_FORMAT_UNKNOWN when no audio format -exists with the given parameters. - - - - - signed or unsigned format - - - - G_LITTLE_ENDIAN or G_BIG_ENDIAN - - - - amount of bits used per sample - - - - amount of used bits in @width - - - - - - Fill @length bytes in @dest with silence samples for @info. - - - - - - - a #GstAudioFormatInfo - - - - a destination - to fill - - - - - - the length to fill - - - - - - Convert the @format string to its #GstAudioFormat. - - - the #GstAudioFormat for @format or GST_AUDIO_FORMAT_UNKNOWN when the -string is not a known format. - - - - - a format string - - - - - - Get the #GstAudioFormatInfo for @format - - - The #GstAudioFormatInfo for @format. - - - - - a #GstAudioFormat - - - - - - - - - - - - - - - - - - The different audio flags that a format info can have. - - integer samples - - - float samples - - - signed samples - - - complex layout - - - the format can be used in -#GstAudioFormatUnpack and #GstAudioFormatPack functions - - - - Information for an audio format. - - - #GstAudioFormat - - - - string representation of the format - - - - user readable description of the format - - - - #GstAudioFormatFlags - - - - the endianness - - - - amount of bits used for one sample - - - - amount of valid bits in @width - - - - @width/8 bytes with 1 silent sample - - - - - - the format of the unpacked samples - - - - function to unpack samples - - - - function to pack samples - - - - - - - - - - Packs @length samples from @src to the data array in format @info. -The samples from source have each channel interleaved -and will be packed into @data. - - - - - - - a #GstAudioFormatInfo - - - - #GstAudioPackFlags - - - - a source array - - - - - - pointer to the destination - data - - - - - - the amount of samples to pack. - - - - - - Unpacks @length samples from the given data of format @info. -The samples will be unpacked into @dest which each channel -interleaved. @dest should at least be big enough to hold @length * -channels * size(unpack_format) bytes. - - - - - - - a #GstAudioFormatInfo - - - - #GstAudioPackFlags - - - - a destination array - - - - - - pointer to the audio data - - - - - - the amount of samples to unpack. - - - - - - Information describing audio properties. This information can be filled -in from GstCaps with gst_audio_info_from_caps(). - -Use the provided macros to access the info in this structure. - - - the format info of the audio - - - - additional audio flags - - - - audio layout - - - - the audio sample rate - - - - the number of channels - - - - the number of bytes for one frame, this is the size of one - sample * @channels - - - - the positions for each channel - - - - - - - - - - - Allocate a new #GstAudioInfo that is also initialized with -gst_audio_info_init(). - - - a new #GstAudioInfo. free with gst_audio_info_free(). - - - - - Converts among various #GstFormat types. This function handles -GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For -raw audio, GST_FORMAT_DEFAULT corresponds to audio frames. This -function can be used to handle pad queries of the type GST_QUERY_CONVERT. - - - TRUE if the conversion was successful. - - - - - a #GstAudioInfo - - - - #GstFormat of the @src_val - - - - value to convert - - - - #GstFormat of the @dest_val - - - - pointer to destination value - - - - - - Copy a GstAudioInfo structure. - - - a new #GstAudioInfo. free with gst_audio_info_free. - - - - - a #GstAudioInfo - - - - - - Free a GstAudioInfo structure previously allocated with gst_audio_info_new() -or gst_audio_info_copy(). - - - - - - - a #GstAudioInfo - - - - - - Parse @caps and update @info. - - - TRUE if @caps could be parsed - - - - - a #GstAudioInfo - - - - a #GstCaps - - - - - - Initialize @info with default values. - - - - - - - a #GstAudioInfo - - - - - - Compares two #GstAudioInfo and returns whether they are equal or not - - - %TRUE if @info and @other are equal, else %FALSE. - - - - - a #GstAudioInfo - - - - a #GstAudioInfo - - - - - - Set the default info for the audio info of @format and @rate and @channels. - -Note: This initializes @info first, no values are preserved. - - - - - - - a #GstAudioInfo - - - - the format - - - - the samplerate - - - - the number of channels - - - - the channel positions - - - - - - - - Convert the values of @info into a #GstCaps. - - - the new #GstCaps containing the - info of @info. - - - - - a #GstAudioInfo - - - - - - - Layout of the audio samples for the different channels. - - interleaved audio - - - non-interleaved audio - - - - #GstAudioDownmixMeta defines an audio downmix matrix to be send along with -audio buffers. These functions in this module help to create and attach the -meta as well as extracting it. - - - parent #GstMeta - - - - the audio properties of the buffer - - - - the number of valid samples in the buffer - - - - the offsets (in bytes) where each channel plane starts in the - buffer or %NULL if the buffer has interleaved layout; if not %NULL, this - is guaranteed to be an array of @info.channels elements - - - - - - - - - - - - - - - - - - - - - Set of available noise shaping methods - - No noise shaping (default) - - - Error feedback - - - Simple 2-pole noise shaping - - - Medium 5-pole noise shaping - - - High 8-pole noise shaping - - - - The different flags that can be used when packing and unpacking. - - No flag - - - When the source has a smaller depth - than the target format, set the least significant bits of the target - to 0. This is likely slightly faster but less accurate. When this flag - is not specified, the most significant bits of the source are duplicated - in the least significant bits of the destination. - - - - - - Free a #GstAudioQuantize. - - - - - - - a #GstAudioQuantize - - - - - - Reset @quant to the state is was when created, clearing any -history it might have. - - - - - - - a #GstAudioQuantize - - - - - - Perform quantization on @samples in @in and write the result to @out. - -In case the samples are interleaved, @in and @out must point to an -array with a single element pointing to a block of interleaved samples. - -If non-interleaved samples are used, @in and @out must point to an -array with pointers to memory blocks, one for each channel. - -@in and @out may point to the same memory location, in which case samples will be -modified in-place. - - - - - - - a #GstAudioQuantize - - - - input samples - - - - output samples - - - - number of samples - - - - - - Create a new quantizer object with the given parameters. - -Output samples will be quantized to a multiple of @quantizer. Better -performance is achieved when @quantizer is a power of 2. - -Dithering and noise-shaping can be performed during quantization with -the @dither and @ns parameters. - - - a new #GstAudioQuantize. Free with gst_audio_quantize_free(). - - - - - a #GstAudioDitherMethod - - - - a #GstAudioNoiseShapingMethod - - - - #GstAudioQuantizeFlags - - - - the #GstAudioFormat of the samples - - - - the amount of channels in the samples - - - - the quantizer to use - - - - - - - Extra flags that can be passed to gst_audio_quantize_new() - - no flags - - - samples are non-interleaved - - - - #GstAudioResampler is a structure which holds the information -required to perform various kinds of resampling filtering. - - - Free a previously allocated #GstAudioResampler @resampler. - - - - - - - a #GstAudioResampler - - - - - - Get the number of input frames that would currently be needed -to produce @out_frames from @resampler. - - - The number of input frames needed for producing -@out_frames of data from @resampler. - - - - - a #GstAudioResampler - - - - number of input frames - - - - - - Get the maximum number of input samples that the resampler would -need before producing output. - - - the latency of @resampler as expressed in the number of -frames. - - - - - a #GstAudioResampler - - - - - - Get the number of output frames that would be currently available when -@in_frames are given to @resampler. - - - The number of frames that would be available after giving -@in_frames as input to @resampler. - - - - - a #GstAudioResampler - - - - number of input frames - - - - - - Perform resampling on @in_frames frames in @in and write @out_frames to @out. - -In case the samples are interleaved, @in and @out must point to an -array with a single element pointing to a block of interleaved samples. - -If non-interleaved samples are used, @in and @out must point to an -array with pointers to memory blocks, one for each channel. - -@in may be %NULL, in which case @in_frames of silence samples are pushed -into the resampler. - -This function always produces @out_frames of output and consumes @in_frames of -input. Use gst_audio_resampler_get_out_frames() and -gst_audio_resampler_get_in_frames() to make sure @in_frames and @out_frames -are matching and @in and @out point to enough memory. - - - - - - - a #GstAudioResampler - - - - input samples - - - - number of input frames - - - - output samples - - - - number of output frames - - - - - - Reset @resampler to the state it was when it was first created, discarding -all sample history. - - - - - - - a #GstAudioResampler - - - - - - Update the resampler parameters for @resampler. This function should -not be called concurrently with any other function on @resampler. - -When @in_rate or @out_rate is 0, its value is unchanged. - -When @options is %NULL, the previously configured options are reused. - - - %TRUE if the new parameters could be set - - - - - a #GstAudioResampler - - - - new input rate - - - - new output rate - - - - new options or %NULL - - - - - - Make a new resampler. - - - The new #GstAudioResampler, or -%NULL on failure. - - - - - a #GstAudioResamplerMethod - - - - #GstAudioResamplerFlags - - - - the #GstAudioFormat - - - - the number of channels - - - - input rate - - - - output rate - - - - extra options - - - - - - Set the parameters for resampling from @in_rate to @out_rate using @method -for @quality in @options. - - - - - - - a #GstAudioResamplerMethod - - - - the quality - - - - the input rate - - - - the output rate - - - - a #GstStructure - - - - - - - The different filter interpolation methods. - - no interpolation - - - linear interpolation of the - filter coefficients. - - - cubic interpolation of the - filter coefficients. - - - - Select for the filter tables should be set up. - - Use interpolated filter tables. This - uses less memory but more CPU and is slightly less accurate but it allows for more - efficient variable rate resampling with gst_audio_resampler_update(). - - - Use full filter table. This uses more memory - but less CPU. - - - Automatically choose between interpolated - and full filter tables. - - - - Different resampler flags. - - no flags - - - input samples are non-interleaved. - an array of blocks of samples, one for each channel, should be passed to the - resample function. - - - output samples are non-interleaved. - an array of blocks of samples, one for each channel, should be passed to the - resample function. - - - optimize for dynamic updates of the sample - rates with gst_audio_resampler_update(). This will select an interpolating filter - when #GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is configured. - - - - Different subsampling and upsampling methods - - Duplicates the samples when - upsampling and drops when downsampling - - - Uses linear interpolation to reconstruct - missing samples and averaging to downsample - - - Uses cubic interpolation - - - Uses Blackman-Nuttall windowed sinc interpolation - - - Uses Kaiser windowed sinc interpolation - - - - This object is the base class for audio ringbuffers used by the base -audio source and sink classes. - -The ringbuffer abstracts a circular buffer of data. One reader and -one writer can operate on the data from different threads in a lockfree -manner. The base class is sufficiently flexible to be used as an -abstraction for DMA based ringbuffers as well as a pure software -implementations. - - - Print debug info about the buffer sized in @spec to the debug log. - - - - - - - the spec to debug - - - - - - Print debug info about the parsed caps in @spec to the debug log. - - - - - - - the spec to debug - - - - - - Parse @caps into @spec. - - - TRUE if the caps could be parsed. - - - - - a spec - - - - a #GstCaps - - - - - - Allocate the resources for the ringbuffer. This function fills -in the data pointer of the ring buffer with a valid #GstBuffer -to which samples can be written. - - - TRUE if the device could be acquired, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to acquire - - - - the specs of the buffer - - - - - - Activate @buf to start or stop pulling data. - -MT safe. - - - TRUE if the device could be activated in the requested mode, -FALSE on error. - - - - - the #GstAudioRingBuffer to activate - - - - the new mode - - - - - - Clear all samples from the ringbuffer. - -MT safe. - - - - - - - the #GstAudioRingBuffer to clear - - - - - - Close the audio device associated with the ring buffer. The ring buffer -should already have been released via gst_audio_ring_buffer_release(). - - - TRUE if the device could be closed, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - Commit @in_samples samples pointed to by @data to the ringbuffer @buf. - -@in_samples and @out_samples define the rate conversion to perform on the -samples in @data. For negative rates, @out_samples must be negative and -@in_samples positive. - -When @out_samples is positive, the first sample will be written at position @sample -in the ringbuffer. When @out_samples is negative, the last sample will be written to -@sample in reverse order. - -@out_samples does not need to be a multiple of the segment size of the ringbuffer -although it is recommended for optimal performance. - -@accum will hold a temporary accumulator used in rate conversion and should be -set to 0 when this function is first called. In case the commit operation is -interrupted, one can resume the processing by passing the previously returned -@accum value back to this function. - -MT safe. - - - The number of samples written to the ringbuffer or -1 on error. The -number of samples written can be less than @out_samples when @buf was interrupted -with a flush or stop. - - - - - the #GstAudioRingBuffer to commit - - - - the sample position of the data - - - - the data to commit - - - - - - the number of samples in the data to commit - - - - the number of samples to write to the ringbuffer - - - - accumulator for rate conversion. - - - - - - Get the number of samples queued in the audio device. This is -usually less than the segment size but can be bigger when the -implementation uses another internal buffer between the audio -device. - -For playback ringbuffers this is the amount of samples transferred from the -ringbuffer to the device but still not played. - -For capture ringbuffers this is the amount of samples in the device that are -not yet transferred to the ringbuffer. - - - The number of samples queued in the audio device. - -MT safe. - - - - - the #GstAudioRingBuffer to query - - - - - - Open the audio device associated with the ring buffer. Does not perform any -setup on the device. You must open the device before acquiring the ring -buffer. - - - TRUE if the device could be opened, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - Pause processing samples from the ringbuffer. - - - TRUE if the device could be paused, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to pause - - - - - - Free the resources of the ringbuffer. - - - TRUE if the device could be released, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to release - - - - - - - - - - - - - - - - - Start processing samples from the ringbuffer. - - - TRUE if the device could be started, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to start - - - - - - Stop processing samples from the ringbuffer. - - - TRUE if the device could be stopped, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to stop - - - - - - Allocate the resources for the ringbuffer. This function fills -in the data pointer of the ring buffer with a valid #GstBuffer -to which samples can be written. - - - TRUE if the device could be acquired, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to acquire - - - - the specs of the buffer - - - - - - Activate @buf to start or stop pulling data. - -MT safe. - - - TRUE if the device could be activated in the requested mode, -FALSE on error. - - - - - the #GstAudioRingBuffer to activate - - - - the new mode - - - - - - Subclasses should call this function to notify the fact that -@advance segments are now processed by the device. - -MT safe. - - - - - - - the #GstAudioRingBuffer to advance - - - - the number of segments written - - - - - - Clear the given segment of the buffer with silence samples. -This function is used by subclasses. - -MT safe. - - - - - - - the #GstAudioRingBuffer to clear - - - - the segment to clear - - - - - - Clear all samples from the ringbuffer. - -MT safe. - - - - - - - the #GstAudioRingBuffer to clear - - - - - - Close the audio device associated with the ring buffer. The ring buffer -should already have been released via gst_audio_ring_buffer_release(). - - - TRUE if the device could be closed, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - Commit @in_samples samples pointed to by @data to the ringbuffer @buf. - -@in_samples and @out_samples define the rate conversion to perform on the -samples in @data. For negative rates, @out_samples must be negative and -@in_samples positive. - -When @out_samples is positive, the first sample will be written at position @sample -in the ringbuffer. When @out_samples is negative, the last sample will be written to -@sample in reverse order. - -@out_samples does not need to be a multiple of the segment size of the ringbuffer -although it is recommended for optimal performance. - -@accum will hold a temporary accumulator used in rate conversion and should be -set to 0 when this function is first called. In case the commit operation is -interrupted, one can resume the processing by passing the previously returned -@accum value back to this function. - -MT safe. - - - The number of samples written to the ringbuffer or -1 on error. The -number of samples written can be less than @out_samples when @buf was interrupted -with a flush or stop. - - - - - the #GstAudioRingBuffer to commit - - - - the sample position of the data - - - - the data to commit - - - - - - the number of samples in the data to commit - - - - the number of samples to write to the ringbuffer - - - - accumulator for rate conversion. - - - - - - Convert @src_val in @src_fmt to the equivalent value in @dest_fmt. The result -will be put in @dest_val. - - - TRUE if the conversion succeeded. - - - - - the #GstAudioRingBuffer - - - - the source format - - - - the source value - - - - the destination format - - - - a location to store the converted value - - - - - - Get the number of samples queued in the audio device. This is -usually less than the segment size but can be bigger when the -implementation uses another internal buffer between the audio -device. - -For playback ringbuffers this is the amount of samples transferred from the -ringbuffer to the device but still not played. - -For capture ringbuffers this is the amount of samples in the device that are -not yet transferred to the ringbuffer. - - - The number of samples queued in the audio device. - -MT safe. - - - - - the #GstAudioRingBuffer to query - - - - - - Checks the status of the device associated with the ring buffer. - - - TRUE if the device was open, FALSE if it was closed. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - Check if the ringbuffer is acquired and ready to use. - - - TRUE if the ringbuffer is acquired, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to check - - - - - - Check if @buf is activated. - -MT safe. - - - TRUE if the device is active. - - - - - the #GstAudioRingBuffer - - - - - - Check if @buf is flushing. - -MT safe. - - - TRUE if the device is flushing. - - - - - the #GstAudioRingBuffer - - - - - - Tell the ringbuffer that it is allowed to start playback when -the ringbuffer is filled with samples. - -MT safe. - - - - - - - the #GstAudioRingBuffer - - - - the new value - - - - - - Open the audio device associated with the ring buffer. Does not perform any -setup on the device. You must open the device before acquiring the ring -buffer. - - - TRUE if the device could be opened, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - Pause processing samples from the ringbuffer. - - - TRUE if the device could be paused, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to pause - - - - - - Returns a pointer to memory where the data from segment @segment -can be found. This function is mostly used by subclasses. - - - FALSE if the buffer is not started. - -MT safe. - - - - - the #GstAudioRingBuffer to read from - - - - the segment to read - - - - - the pointer to the memory where samples can be read - - - - - - the number of bytes to read - - - - - - Read @len samples from the ringbuffer into the memory pointed -to by @data. -The first sample should be read from position @sample in -the ringbuffer. - -@len should not be a multiple of the segment size of the ringbuffer -although it is recommended. - -@timestamp will return the timestamp associated with the data returned. - - - The number of samples read from the ringbuffer or -1 on -error. - -MT safe. - - - - - the #GstAudioRingBuffer to read from - - - - the sample position of the data - - - - where the data should be read - - - - - - the number of samples in data to read - - - - where the timestamp is returned - - - - - - Free the resources of the ringbuffer. - - - TRUE if the device could be released, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to release - - - - - - Get the number of samples that were processed by the ringbuffer -since it was last started. This does not include the number of samples not -yet processed (see gst_audio_ring_buffer_delay()). - - - The number of samples processed by the ringbuffer. - -MT safe. - - - - - the #GstAudioRingBuffer to query - - - - - - Sets the given callback function on the buffer. This function -will be called every time a segment has been written to a device. - -MT safe. - - - - - - - the #GstAudioRingBuffer to set the callback on - - - - the callback to set - - - - user data passed to the callback - - - - - - Sets the given callback function on the buffer. This function -will be called every time a segment has been written to a device. - -MT safe. - - - - - - - the #GstAudioRingBuffer to set the callback on - - - - the callback to set - - - - user data passed to the callback - - - - function to be called when @user_data is no longer needed - - - - - - Tell the ringbuffer about the device's channel positions. This must -be called in when the ringbuffer is acquired. - - - - - - - the #GstAudioRingBuffer - - - - the device channel positions - - - - - - - - Set the ringbuffer to flushing mode or normal mode. - -MT safe. - - - - - - - the #GstAudioRingBuffer to flush - - - - the new mode - - - - - - Make sure that the next sample written to the device is -accounted for as being the @sample sample written to the -device. This value will be used in reporting the current -sample position of the ringbuffer. - -This function will also clear the buffer with silence. - -MT safe. - - - - - - - the #GstAudioRingBuffer to use - - - - the sample number to set - - - - - - - - - - - - - - - - - - - - - - - Start processing samples from the ringbuffer. - - - TRUE if the device could be started, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to start - - - - - - Stop processing samples from the ringbuffer. - - - TRUE if the device could be stopped, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to stop - - - - - - - - - used to signal start/stop/pause/resume actions - - - - boolean indicating that the ringbuffer is open - - - - boolean indicating that the ringbuffer is acquired - - - - data in the ringbuffer - - - - size of data in the ringbuffer - - - - - - - format and layout of the ringbuffer data - - - - number of samples in one segment - - - - pointer to memory holding one segment of silence samples - - - - state of the buffer - - - - readpointer in the ringbuffer - - - - segment corresponding to segment 0 (unused) - - - - is a reader or writer waiting for a free segment - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function is set with gst_audio_ring_buffer_set_callback() and is -called to fill the memory at @data with @len bytes of samples. - - - - - - - a #GstAudioRingBuffer - - - - target to fill - - - - - - amount to fill - - - - user data - - - - - - The vmethods that subclasses can override to implement the ringbuffer. - - - parent class - - - - - - - TRUE if the device could be opened, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - - - - - TRUE if the device could be acquired, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to acquire - - - - the specs of the buffer - - - - - - - - - - TRUE if the device could be released, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to release - - - - - - - - - - TRUE if the device could be closed, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer - - - - - - - - - - TRUE if the device could be started, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to start - - - - - - - - - - TRUE if the device could be paused, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to pause - - - - - - - - - - - - - - - - - - - - - - - TRUE if the device could be stopped, FALSE on error. - -MT safe. - - - - - the #GstAudioRingBuffer to stop - - - - - - - - - - The number of samples queued in the audio device. - -MT safe. - - - - - the #GstAudioRingBuffer to query - - - - - - - - - - TRUE if the device could be activated in the requested mode, -FALSE on error. - - - - - the #GstAudioRingBuffer to activate - - - - the new mode - - - - - - - - - - The number of samples written to the ringbuffer or -1 on error. The -number of samples written can be less than @out_samples when @buf was interrupted -with a flush or stop. - - - - - the #GstAudioRingBuffer to commit - - - - the sample position of the data - - - - the data to commit - - - - - - the number of samples in the data to commit - - - - the number of samples to write to the ringbuffer - - - - accumulator for rate conversion. - - - - - - - - - - - - - - the #GstAudioRingBuffer to clear - - - - - - - - - - - - - The format of the samples in the ringbuffer. - - samples in linear or float - - - samples in mulaw - - - samples in alaw - - - samples in ima adpcm - - - samples in mpeg audio (but not AAC) format - - - samples in gsm format - - - samples in IEC958 frames (e.g. AC3) - - - samples in AC3 format - - - samples in EAC3 format - - - samples in DTS format - - - samples in MPEG-2 AAC ADTS format - - - samples in MPEG-4 AAC ADTS format - - - samples in MPEG-2 AAC raw format (Since: 1.12) - - - samples in MPEG-4 AAC raw format (Since: 1.12) - - - samples in FLAC format (Since: 1.12) - - - - The structure containing the format specification of the ringbuffer. - - - The caps that generated the Spec. - - - - the sample type - - - - the #GstAudioInfo - - - - the latency in microseconds - - - - the total buffer size in microseconds - - - - the size of one segment in bytes - - - - the total number of segments - - - - number of segments queued in the lower level device, - defaults to segtotal - - - - - - - - - - The state of the ringbuffer. - - The ringbuffer is stopped - - - The ringbuffer is paused - - - The ringbuffer is started - - - The ringbuffer has encountered an - error after it has been started, e.g. because the device was - disconnected (Since: 1.2) - - - - This is the most simple base class for audio sinks that only requires -subclasses to implement a set of simple functions: - -* `open()` :Open the device. - -* `prepare()` :Configure the device with the specified format. - -* `write()` :Write samples to the device. - -* `reset()` :Unblock writes and flush the device. - -* `delay()` :Get the number of samples written but not yet played -by the device. - -* `unprepare()` :Undo operations done by prepare. - -* `close()` :Close the device. - -All scheduling of samples and timestamps is done in this base class -together with #GstAudioBaseSink using a default implementation of a -#GstAudioRingBuffer that uses threads. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the parent class structure. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - class extension structure. Since: 1.18 - - - - - - - - - - - - - - - - - - - - - This is the most simple base class for audio sources that only requires -subclasses to implement a set of simple functions: - -* `open()` :Open the device. -* `prepare()` :Configure the device with the specified format. -* `read()` :Read samples from the device. -* `reset()` :Unblock reads and flush the device. -* `delay()` :Get the number of samples in the device but not yet read. -* `unprepare()` :Undo operations done by prepare. -* `close()` :Close the device. - -All scheduling of samples and timestamps is done in this base class -together with #GstAudioBaseSrc using a default implementation of a -#GstAudioRingBuffer that uses threads. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioSrc class. Override the vmethod to implement -functionality. - - - the parent class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstAudioStreamAlign provides a helper object that helps tracking audio -stream alignment and discontinuities, and detects discontinuities if -possible. - -See gst_audio_stream_align_new() for a description of its parameters and -gst_audio_stream_align_process() for the details of the processing. - - - Allocate a new #GstAudioStreamAlign with the given configuration. All -processing happens according to sample rate @rate, until -gst_audio_stream_align_set_rate() is called with a new @rate. -A negative rate can be used for reverse playback. - -@alignment_threshold gives the tolerance in nanoseconds after which a -timestamp difference is considered a discontinuity. Once detected, -@discont_wait nanoseconds have to pass without going below the threshold -again until the output buffer is marked as a discontinuity. These can later -be re-configured with gst_audio_stream_align_set_alignment_threshold() and -gst_audio_stream_align_set_discont_wait(). - - - a new #GstAudioStreamAlign. free with gst_audio_stream_align_free(). - - - - - a sample rate - - - - a alignment threshold in nanoseconds - - - - discont wait in nanoseconds - - - - - - Copy a GstAudioStreamAlign structure. - - - a new #GstAudioStreamAlign. free with gst_audio_stream_align_free. - - - - - a #GstAudioStreamAlign - - - - - - Free a GstAudioStreamAlign structure previously allocated with gst_audio_stream_align_new() -or gst_audio_stream_align_copy(). - - - - - - - a #GstAudioStreamAlign - - - - - - Gets the currently configured alignment threshold. - - - The currently configured alignment threshold - - - - - a #GstAudioStreamAlign - - - - - - Gets the currently configured discont wait. - - - The currently configured discont wait - - - - - a #GstAudioStreamAlign - - - - - - Gets the currently configured sample rate. - - - The currently configured sample rate - - - - - a #GstAudioStreamAlign - - - - - - Returns the number of samples that were processed since the last -discontinuity was detected. - - - The number of samples processed since the last discontinuity. - - - - - a #GstAudioStreamAlign - - - - - - Timestamp that was passed when a discontinuity was detected, i.e. the first -timestamp after the discontinuity. - - - The last timestamp at when a discontinuity was detected - - - - - a #GstAudioStreamAlign - - - - - - Marks the next buffer as discontinuous and resets timestamp tracking. - - - - - - - a #GstAudioStreamAlign - - - - - - Processes data with @timestamp and @n_samples, and returns the output -timestamp, duration and sample position together with a boolean to signal -whether a discontinuity was detected or not. All non-discontinuous data -will have perfect timestamps and durations. - -A discontinuity is detected once the difference between the actual -timestamp and the timestamp calculated from the sample count since the last -discontinuity differs by more than the alignment threshold for a duration -longer than discont wait. - -Note: In reverse playback, every buffer is considered discontinuous in the -context of buffer flags because the last sample of the previous buffer is -discontinuous with the first sample of the current one. However for this -function they are only considered discontinuous in reverse playback if the -first sample of the previous buffer is discontinuous with the last sample -of the current one. - - - %TRUE if a discontinuity was detected, %FALSE otherwise. - - - - - a #GstAudioStreamAlign - - - - if this data is considered to be discontinuous - - - - a #GstClockTime of the start of the data - - - - number of samples to process - - - - output timestamp of the data - - - - output duration of the data - - - - output sample position of the start of the data - - - - - - Sets @alignment_treshold as new alignment threshold for the following processing. - - - - - - - a #GstAudioStreamAlign - - - - a new alignment threshold - - - - - - Sets @alignment_treshold as new discont wait for the following processing. - - - - - - - a #GstAudioStreamAlign - - - - a new discont wait - - - - - - Sets @rate as new sample rate for the following processing. If the sample -rate differs this implicitly marks the next data as discontinuous. - - - - - - - a #GstAudioStreamAlign - - - - a new sample rate - - - - - - - Calculate frames from @clocktime and sample @rate. - - - - clock time - - - sampling rate - - - - - Calculate clocktime from sample @frames and @rate. - - - - sample frames - - - sampling rate - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This metadata stays relevant as long as channels are unchanged. - - - - - This metadata stays relevant as long as sample rate is unchanged. - - - - - This metadata is relevant for audio streams. - - - - - - - - - - - - This interface is implemented by elements that provide a stream volume. Examples for -such elements are #volume and #playbin. - -Applications can use this interface to get or set the current stream volume. For this -the "volume" #GObject property can be used or the helper functions gst_stream_volume_set_volume() -and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted -1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to -a different format by using gst_stream_volume_convert_volume(). Volume sliders should usually -use a cubic volume. - -Separate from the volume the stream can also be muted by the "mute" #GObject property or -gst_stream_volume_set_mute() and gst_stream_volume_get_mute(). - -Elements that provide some kind of stream volume should implement the "volume" and -"mute" #GObject properties and handle setting and getting of them properly. -The volume property is defined to be a linear volume factor. - - - - - the converted volume - - - - - #GstStreamVolumeFormat to convert from - - - - #GstStreamVolumeFormat to convert to - - - - Volume in @from format that should be converted - - - - - - - - Returns %TRUE if the stream is muted - - - - - #GstStreamVolume that should be used - - - - - - - - The current stream volume as linear factor - - - - - #GstStreamVolume that should be used - - - - #GstStreamVolumeFormat which should be returned - - - - - - - - - - - - #GstStreamVolume that should be used - - - - Mute state that should be set - - - - - - - - - - - - #GstStreamVolume that should be used - - - - #GstStreamVolumeFormat of @val - - - - Linear volume factor that should be set - - - - - - - - - - - - - Different representations of a stream volume. gst_stream_volume_convert_volume() -allows to convert between the different representations. - -Formulas to convert from a linear to a cubic or dB volume are -cbrt(val) and 20 * log10 (val). - - - Linear scale factor, 1.0 = 100% - - - Cubic volume scale - - - Logarithmic volume scale (dB, amplitude not power) - - - - - - - - - - Clip the buffer to the given %GstSegment. - -After calling this function the caller does not own a reference to -@buffer anymore. - - - %NULL if the buffer is completely outside the configured segment, -otherwise the clipped buffer is returned. - -If the buffer has no timestamp, it is assumed to be inside the segment and -is not clipped - - - - - The buffer to clip. - - - - Segment in %GST_FORMAT_TIME or %GST_FORMAT_DEFAULT to which - the buffer should be clipped. - - - - sample rate. - - - - size of one audio frame in bytes. This is the size of one sample * -number of channels. - - - - - - Reorders @buffer from the channel positions @from to the channel -positions @to. @from and @to must contain the same number of -positions and the same positions, only in a different order. -@buffer must be writable. - - - %TRUE if the reordering was possible. - - - - - The buffer to reorder. - - - - The %GstAudioFormat of the buffer. - - - - The number of channels. - - - - The channel positions in the buffer. - - - - - - The channel positions to convert to. - - - - - - - - Truncate the buffer to finally have @samples number of samples, removing -the necessary amount of samples from the end and @trim number of samples -from the beginning. - -After calling this function the caller does not own a reference to -@buffer anymore. - - - the truncated buffer or %NULL if the arguments - were invalid - - - - - The buffer to truncate. - - - - size of one audio frame in bytes. This is the size of one sample * -number of channels. - - - - the number of samples to remove from the beginning of the buffer - - - - the final number of samples that should exist in this buffer or -1 -to use all the remaining samples if you are only removing samples from the -beginning. - - - - - - Get the fallback channel-mask for the given number of channels. - -This function returns a reasonable fallback channel-mask and should be -called as a last resort when the specific channel map is unknown. - - - a fallback channel-mask for @channels or 0 when there is no -mask and mono. - - - - - the number of channels - - - - - - Create a new channel mixer object for the given parameters. - - - a new #GstAudioChannelMixer object, or %NULL if @format isn't supported. - Free with gst_audio_channel_mixer_free() after usage. - - - - - #GstAudioChannelMixerFlags - - - - - - - number of input channels - - - - positions of input channels - - - - number of output channels - - - - positions of output channels - - - - - - Create a new channel mixer object for the given parameters. - - - a new #GstAudioChannelMixer object, or %NULL if @format isn't supported, - @matrix is invalid, or @matrix is %NULL and @in_channels != @out_channels. - Free with gst_audio_channel_mixer_free() after usage. - - - - - #GstAudioChannelMixerFlags - - - - - - - number of input channels - - - - number of output channels - - - - channel conversion matrix, m[@in_channels][@out_channels]. - If identity matrix, passthrough applies. If %NULL, a (potentially truncated) - identity matrix is generated. - - - - - - Convert the @channels present in @channel_mask to a @position array -(which should have at least @channels entries ensured by caller). -If @channel_mask is set to 0, it is considered as 'not present' for purpose -of conversion. -A partially valid @channel_mask with less bits set than the number -of channels is considered valid. - - - %TRUE if channel and channel mask are valid and could be converted - - - - - The number of channels - - - - The input channel_mask - - - - The - %GstAudioChannelPosition<!-- -->s - - - - - - - - Convert the @position array of @channels channels to a bitmask. - -If @force_order is %TRUE it additionally checks if the channels are -in the order required by GStreamer. - - - %TRUE if the channel positions are valid and could be converted. - - - - - The %GstAudioChannelPositions - - - - - - The number of channels. - - - - Only consider the GStreamer channel order. - - - - the output channel mask - - - - - - Converts @position to a human-readable string representation for -debugging purposes. - - - a newly allocated string representing -@position - - - - - The %GstAudioChannelPositions - to convert. - - - - - - The number of channels. - - - - - - Reorders the channel positions in @position from any order to -the GStreamer channel order. - - - %TRUE if the channel positions are valid and reordering -was successful. - - - - - The channel positions to - reorder to. - - - - - - The number of channels. - - - - - - Checks if @position contains valid channel positions for -@channels channels. If @force_order is %TRUE it additionally -checks if the channels are in the order required by GStreamer. - - - %TRUE if the channel positions are valid. - - - - - The %GstAudioChannelPositions - to check. - - - - - - The number of channels. - - - - Only consider the GStreamer channel order. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Construct a #GstAudioFormat with given parameters. - - - a #GstAudioFormat or GST_AUDIO_FORMAT_UNKNOWN when no audio format -exists with the given parameters. - - - - - signed or unsigned format - - - - G_LITTLE_ENDIAN or G_BIG_ENDIAN - - - - amount of bits used per sample - - - - amount of used bits in @width - - - - - - Fill @length bytes in @dest with silence samples for @info. - - - - - - - a #GstAudioFormatInfo - - - - a destination - to fill - - - - - - the length to fill - - - - - - Convert the @format string to its #GstAudioFormat. - - - the #GstAudioFormat for @format or GST_AUDIO_FORMAT_UNKNOWN when the -string is not a known format. - - - - - a format string - - - - - - Get the #GstAudioFormatInfo for @format - - - The #GstAudioFormatInfo for @format. - - - - - a #GstAudioFormat - - - - - - - - - - - - - - - - - - - - - - - Return all the raw audio formats supported by GStreamer. - - - an array of #GstAudioFormat - - - - - - - the number of elements in the returned array - - - - - - Returns a reorder map for @from to @to that can be used in -custom channel reordering code, e.g. to convert from or to the -GStreamer channel order. @from and @to must contain the same -number of positions and the same positions, only in a -different order. - -The resulting @reorder_map can be used for reordering by assigning -channel i of the input to channel reorder_map[i] of the output. - - - %TRUE if the channel positions are valid and reordering -is possible. - - - - - The number of channels. - - - - The channel positions to reorder from. - - - - - - The channel positions to reorder to. - - - - - - Pointer to the reorder map. - - - - - - - - Calculated the size of the buffer expected by gst_audio_iec61937_payload() for -payloading type from @spec. - - - the size or 0 if the given @type is not supported or cannot be -payloaded. - - - - - the ringbufer spec - - - - - - Payloads @src in the form specified by IEC 61937 for the type from @spec and -stores the result in @dst. @src must contain exactly one frame of data and -the frame is not checked for errors. - - - transfer-full: %TRUE if the payloading was successful, %FALSE -otherwise. - - - - - a buffer containing the data to payload - - - - - - size of @src in bytes - - - - the destination buffer to store the - payloaded contents in. Should not overlap with @src - - - - - - size of @dst in bytes - - - - the ringbufer spec for @src - - - - the expected byte order of the payloaded data - - - - - - Return a generic raw audio caps for formats defined in @formats. -If @formats is %NULL returns a caps for all the supported raw audio formats, -see gst_audio_formats_raw(). - - - an audio @GstCaps - - - - - an array of raw #GstAudioFormat, or %NULL - - - - - - the size of @formats - - - - the layout of audio samples - - - - - - - - - - - - - - - - - - Create a new quantizer object with the given parameters. - -Output samples will be quantized to a multiple of @quantizer. Better -performance is achieved when @quantizer is a power of 2. - -Dithering and noise-shaping can be performed during quantization with -the @dither and @ns parameters. - - - a new #GstAudioQuantize. Free with gst_audio_quantize_free(). - - - - - a #GstAudioDitherMethod - - - - a #GstAudioNoiseShapingMethod - - - - #GstAudioQuantizeFlags - - - - the #GstAudioFormat of the samples - - - - the amount of channels in the samples - - - - the quantizer to use - - - - - - Reorders @data from the channel positions @from to the channel -positions @to. @from and @to must contain the same number of -positions and the same positions, only in a different order. - -Note: this function assumes the audio data is in interleaved layout - - - %TRUE if the reordering was possible. - - - - - The pointer to - the memory. - - - - - - The size of the memory. - - - - The %GstAudioFormat of the buffer. - - - - The number of channels. - - - - The channel positions in the buffer. - - - - - - The channel positions to convert to. - - - - - - - - Make a new resampler. - - - The new #GstAudioResampler, or -%NULL on failure. - - - - - a #GstAudioResamplerMethod - - - - #GstAudioResamplerFlags - - - - the #GstAudioFormat - - - - the number of channels - - - - input rate - - - - output rate - - - - extra options - - - - - - Set the parameters for resampling from @in_rate to @out_rate using @method -for @quality in @options. - - - - - - - a #GstAudioResamplerMethod - - - - the quality - - - - the input rate - - - - the output rate - - - - a #GstStructure - - - - - - Attaches #GstAudioClippingMeta metadata to @buffer with the given parameters. - - - the #GstAudioClippingMeta on @buffer. - - - - - a #GstBuffer - - - - GstFormat of @start and @stop, GST_FORMAT_DEFAULT is samples - - - - Amount of audio to clip from start of buffer - - - - Amount of to clip from end of buffer - - - - - - Attaches #GstAudioDownmixMeta metadata to @buffer with the given parameters. - -@matrix is an two-dimensional array of @to_channels times @from_channels -coefficients, i.e. the i-th output channels is constructed by multiplicating -the input channels with the coefficients in @matrix[i] and taking the sum -of the results. - - - the #GstAudioDownmixMeta on @buffer. - - - - - a #GstBuffer - - - - the channel positions - of the source - - - - - - The number of channels of the source - - - - the channel positions of - the destination - - - - - - The number of channels of the destination - - - - The matrix coefficients. - - - - - - Allocates and attaches a #GstAudioMeta on @buffer, which must be writable -for that purpose. The fields of the #GstAudioMeta are directly populated -from the arguments of this function. - -When @info->layout is %GST_AUDIO_LAYOUT_NON_INTERLEAVED and @offsets is -%NULL, the offsets are calculated with a formula that assumes the planes are -tightly packed and in sequence: -offsets[channel] = channel * @samples * sample_stride - -It is not allowed for channels to overlap in memory, -i.e. for each i in [0, channels), the range -[@offsets[i], @offsets[i] + @samples * sample_stride) must not overlap -with any other such range. This function will assert if the parameters -specified cause this restriction to be violated. - -It is, obviously, also not allowed to specify parameters that would cause -out-of-bounds memory access on @buffer. This is also checked, which means -that you must add enough memory on the @buffer before adding this meta. - - - the #GstAudioMeta that was attached on the @buffer - - - - - a #GstBuffer - - - - the audio properties of the buffer - - - - the number of valid samples in the buffer - - - - the offsets (in bytes) where each channel plane starts - in the buffer or %NULL to calculate it (see below); must be %NULL also - when @info->layout is %GST_AUDIO_LAYOUT_INTERLEAVED - - - - - - - - - - - - - - - - - - - - Find the #GstAudioDownmixMeta on @buffer for the given destination -channel positions. - - - the #GstAudioDownmixMeta on @buffer. - - - - - a #GstBuffer - - - - the channel positions of - the destination - - - - - - The number of channels of the destination - - - - - - - - - - - - - - - the converted volume - - - - - #GstStreamVolumeFormat to convert from - - - - #GstStreamVolumeFormat to convert to - - - - Volume in @from format that should be converted - - - - - - diff --git a/gir-files/GstBase-1.0.gir b/gir-files/GstBase-1.0.gir deleted file mode 100644 index 8b1f032c3..000000000 --- a/gir-files/GstBase-1.0.gir +++ /dev/null @@ -1,13869 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Convenience macro to access the source pad of #GstAggregator - - - - a #GstAggregator - - - - - This class is for elements that receive buffers in an undesired size. -While for example raw video contains one image per buffer, the same is not -true for a lot of other formats, especially those that come directly from -a file. So if you have undefined buffer sizes and require a specific size, -this object is for you. - -An adapter is created with gst_adapter_new(). It can be freed again with -g_object_unref(). - -The theory of operation is like this: All buffers received are put -into the adapter using gst_adapter_push() and the data is then read back -in chunks of the desired size using gst_adapter_map()/gst_adapter_unmap() -and/or gst_adapter_copy(). After the data has been processed, it is freed -using gst_adapter_unmap(). - -Other methods such as gst_adapter_take() and gst_adapter_take_buffer() -combine gst_adapter_map() and gst_adapter_unmap() in one method and are -potentially more convenient for some use cases. - -For example, a sink pad's chain function that needs to pass data to a library -in 512-byte chunks could be implemented like this: -|[<!-- language="C" --> -static GstFlowReturn -sink_pad_chain (GstPad *pad, GstObject *parent, GstBuffer *buffer) -{ - MyElement *this; - GstAdapter *adapter; - GstFlowReturn ret = GST_FLOW_OK; - - this = MY_ELEMENT (parent); - - adapter = this->adapter; - - // put buffer into adapter - gst_adapter_push (adapter, buffer); - - // while we can read out 512 bytes, process them - while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) { - const guint8 *data = gst_adapter_map (adapter, 512); - // use flowreturn as an error value - ret = my_library_foo (data); - gst_adapter_unmap (adapter); - gst_adapter_flush (adapter, 512); - } - return ret; -} -]| - -For another example, a simple element inside GStreamer that uses #GstAdapter -is the libvisual element. - -An element using #GstAdapter in its sink pad chain function should ensure that -when the FLUSH_STOP event is received, that any queued data is cleared using -gst_adapter_clear(). Data should also be cleared or processed on EOS and -when changing state from %GST_STATE_PAUSED to %GST_STATE_READY. - -Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might -need to clear the adapter after a discontinuity. - -The adapter will keep track of the timestamps of the buffers -that were pushed. The last seen timestamp before the current position -can be queried with gst_adapter_prev_pts(). This function can -optionally return the number of bytes between the start of the buffer that -carried the timestamp and the current adapter position. The distance is -useful when dealing with, for example, raw audio samples because it allows -you to calculate the timestamp of the current adapter position by using the -last seen timestamp and the amount of bytes since. Additionally, the -gst_adapter_prev_pts_at_offset() can be used to determine the last -seen timestamp at a particular offset in the adapter. - -The adapter will also keep track of the offset of the buffers -(#GST_BUFFER_OFFSET) that were pushed. The last seen offset before the -current position can be queried with gst_adapter_prev_offset(). This function -can optionally return the number of bytes between the start of the buffer -that carried the offset and the current adapter position. - -Additionally the adapter also keeps track of the PTS, DTS and buffer offset -at the last discontinuity, which can be retrieved with -gst_adapter_pts_at_discont(), gst_adapter_dts_at_discont() and -gst_adapter_offset_at_discont(). The number of bytes that were consumed -since then can be queried with gst_adapter_distance_from_discont(). - -A last thing to note is that while #GstAdapter is pretty optimized, -merging buffers still might be an operation that requires a `malloc()` and -`memcpy()` operation, and these operations are not the fastest. Because of -this, some functions like gst_adapter_available_fast() are provided to help -speed up such cases should you want to. To avoid repeated memory allocations, -gst_adapter_copy() can be used to copy data into a (statically allocated) -user provided buffer. - -#GstAdapter is not MT safe. All operations on an adapter must be serialized by -the caller. This is not normally a problem, however, as the normal use case -of #GstAdapter is inside one pad's chain function, in which case access is -serialized via the pad's STREAM_LOCK. - -Note that gst_adapter_push() takes ownership of the buffer passed. Use -gst_buffer_ref() before pushing it into the adapter if you still want to -access the buffer later. The adapter will never modify the data in the -buffer pushed in it. - - - Creates a new #GstAdapter. Free with g_object_unref(). - - - a new #GstAdapter - - - - - Gets the maximum amount of bytes available, that is it returns the maximum -value that can be supplied to gst_adapter_map() without that function -returning %NULL. - - - number of bytes available in @adapter - - - - - a #GstAdapter - - - - - - Gets the maximum number of bytes that are immediately available without -requiring any expensive operations (like copying the data into a -temporary buffer). - - - number of bytes that are available in @adapter without expensive -operations - - - - - a #GstAdapter - - - - - - Removes all buffers from @adapter. - - - - - - - a #GstAdapter - - - - - - Copies @size bytes of data starting at @offset out of the buffers -contained in #GstAdapter into an array @dest provided by the caller. - -The array @dest should be large enough to contain @size bytes. -The user should check that the adapter has (@offset + @size) bytes -available before calling this function. - - - - - - - a #GstAdapter - - - - - the memory to copy into - - - - - - the bytes offset in the adapter to start from - - - - the number of bytes to copy - - - - - - Similar to gst_adapter_copy, but more suitable for language bindings. @size -bytes of data starting at @offset will be copied out of the buffers contained -in @adapter and into a new #GBytes structure which is returned. Depending on -the value of the @size argument an empty #GBytes structure may be returned. - - - A new #GBytes structure containing the copied data. - - - - - a #GstAdapter - - - - the bytes offset in the adapter to start from - - - - the number of bytes to copy - - - - - - Get the distance in bytes since the last buffer with the -%GST_BUFFER_FLAG_DISCONT flag. - -The distance will be reset to 0 for all buffers with -%GST_BUFFER_FLAG_DISCONT on them, and then calculated for all other -following buffers based on their size. - - - The offset. Can be %GST_BUFFER_OFFSET_NONE. - - - - - a #GstAdapter - - - - - - Get the DTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_CLOCK_TIME_NONE. - - - The DTS at the last discont or GST_CLOCK_TIME_NONE. - - - - - a #GstAdapter - - - - - - Flushes the first @flush bytes in the @adapter. The caller must ensure that -at least this many bytes are available. - -See also: gst_adapter_map(), gst_adapter_unmap() - - - - - - - a #GstAdapter - - - - the number of bytes to flush - - - - - - Returns a #GstBuffer containing the first @nbytes of the @adapter, but -does not flush them from the adapter. See gst_adapter_take_buffer() -for details. - -Caller owns a reference to the returned buffer. gst_buffer_unref() after -usage. - -Free-function: gst_buffer_unref - - - a #GstBuffer containing the first - @nbytes of the adapter, or %NULL if @nbytes bytes are not available. - gst_buffer_unref() when no longer needed. - - - - - a #GstAdapter - - - - the number of bytes to get - - - - - - Returns a #GstBuffer containing the first @nbytes of the @adapter, but -does not flush them from the adapter. See gst_adapter_take_buffer_fast() -for details. - -Caller owns a reference to the returned buffer. gst_buffer_unref() after -usage. - -Free-function: gst_buffer_unref - - - a #GstBuffer containing the first - @nbytes of the adapter, or %NULL if @nbytes bytes are not available. - gst_buffer_unref() when no longer needed. - - - - - a #GstAdapter - - - - the number of bytes to get - - - - - - Returns a #GstBufferList of buffers containing the first @nbytes bytes of -the @adapter but does not flush them from the adapter. See -gst_adapter_take_buffer_list() for details. - -Caller owns the returned list. Call gst_buffer_list_unref() to free -the list after usage. - - - a #GstBufferList of buffers containing - the first @nbytes of the adapter, or %NULL if @nbytes bytes are not - available - - - - - a #GstAdapter - - - - the number of bytes to get - - - - - - Returns a #GList of buffers containing the first @nbytes bytes of the -@adapter, but does not flush them from the adapter. See -gst_adapter_take_list() for details. - -Caller owns returned list and contained buffers. gst_buffer_unref() each -buffer in the list before freeing the list after usage. - - - a #GList of - buffers containing the first @nbytes of the adapter, or %NULL if @nbytes - bytes are not available - - - - - - - a #GstAdapter - - - - the number of bytes to get - - - - - - Gets the first @size bytes stored in the @adapter. The returned pointer is -valid until the next function is called on the adapter. - -Note that setting the returned pointer as the data of a #GstBuffer is -incorrect for general-purpose plugins. The reason is that if a downstream -element stores the buffer so that it has access to it outside of the bounds -of its chain function, the buffer will have an invalid data pointer after -your element flushes the bytes. In that case you should use -gst_adapter_take(), which returns a freshly-allocated buffer that you can set -as #GstBuffer memory or the potentially more performant -gst_adapter_take_buffer(). - -Returns %NULL if @size bytes are not available. - - - - a pointer to the first @size bytes of data, or %NULL - - - - - - - a #GstAdapter - - - - the number of bytes to map/peek - - - - - - Scan for pattern @pattern with applied mask @mask in the adapter data, -starting from offset @offset. - -The bytes in @pattern and @mask are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -adapter for it to match, even if the first or last bytes are masked out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the adapter. - -This function calls gst_adapter_masked_scan_uint32_peek() passing %NULL -for value. - - - offset of the first match, or -1 if no match was found. - -Example: -|[ -// Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff - -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256); -// -> returns 0 -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255); -// -> returns -1 -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255); -// -> returns 1 -gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256); -// -> returns -1 -gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256); -// -> returns 0 -gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256); -// -> returns 2 -gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4); -// -> returns -1 -]| - - - - - a #GstAdapter - - - - mask to apply to data before matching against @pattern - - - - pattern to match (after mask is applied) - - - - offset into the adapter data from which to start scanning, returns - the last scanned position. - - - - number of bytes to scan from offset - - - - - - Scan for pattern @pattern with applied mask @mask in the adapter data, -starting from offset @offset. If a match is found, the value that matched -is returned through @value, otherwise @value is left untouched. - -The bytes in @pattern and @mask are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -adapter for it to match, even if the first or last bytes are masked out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the adapter. - - - offset of the first match, or -1 if no match was found. - - - - - a #GstAdapter - - - - mask to apply to data before matching against @pattern - - - - pattern to match (after mask is applied) - - - - offset into the adapter data from which to start scanning, returns - the last scanned position. - - - - number of bytes to scan from offset - - - - pointer to uint32 to return matching data - - - - - - Get the offset that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_BUFFER_OFFSET_NONE. - - - The offset at the last discont or GST_BUFFER_OFFSET_NONE. - - - - - a #GstAdapter - - - - - - Get the dts that was before the current byte in the adapter. When -@distance is given, the amount of bytes between the dts and the current -position is returned. - -The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a dts is removed from the adapter, the dts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. - - - The previously seen dts. - - - - - a #GstAdapter - - - - pointer to location for distance, or %NULL - - - - - - Get the dts that was before the byte at offset @offset in the adapter. When -@distance is given, the amount of bytes between the dts and the current -position is returned. - -The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a dts is removed from the adapter, the dts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. - - - The previously seen dts at given offset. - - - - - a #GstAdapter - - - - the offset in the adapter at which to get timestamp - - - - pointer to location for distance, or %NULL - - - - - - Get the offset that was before the current byte in the adapter. When -@distance is given, the amount of bytes between the offset and the current -position is returned. - -The offset is reset to GST_BUFFER_OFFSET_NONE and the distance is set to 0 -when the adapter is first created or when it is cleared. This also means that -before the first byte with an offset is removed from the adapter, the offset -and distance returned are GST_BUFFER_OFFSET_NONE and 0 respectively. - - - The previous seen offset. - - - - - a #GstAdapter - - - - pointer to a location for distance, or %NULL - - - - - - Get the pts that was before the current byte in the adapter. When -@distance is given, the amount of bytes between the pts and the current -position is returned. - -The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a pts is removed from the adapter, the pts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. - - - The previously seen pts. - - - - - a #GstAdapter - - - - pointer to location for distance, or %NULL - - - - - - Get the pts that was before the byte at offset @offset in the adapter. When -@distance is given, the amount of bytes between the pts and the current -position is returned. - -The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a pts is removed from the adapter, the pts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. - - - The previously seen pts at given offset. - - - - - a #GstAdapter - - - - the offset in the adapter at which to get timestamp - - - - pointer to location for distance, or %NULL - - - - - - Get the PTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_CLOCK_TIME_NONE. - - - The PTS at the last discont or GST_CLOCK_TIME_NONE. - - - - - a #GstAdapter - - - - - - Adds the data from @buf to the data stored inside @adapter and takes -ownership of the buffer. - - - - - - - a #GstAdapter - - - - a #GstBuffer to add to queue in the adapter - - - - - - Returns a freshly allocated buffer containing the first @nbytes bytes of the -@adapter. The returned bytes will be flushed from the adapter. - -Caller owns returned value. g_free after usage. - -Free-function: g_free - - - - oven-fresh hot data, or %NULL if @nbytes bytes are not available - - - - - - - a #GstAdapter - - - - the number of bytes to take - - - - - - Returns a #GstBuffer containing the first @nbytes bytes of the -@adapter. The returned bytes will be flushed from the adapter. -This function is potentially more performant than -gst_adapter_take() since it can reuse the memory in pushed buffers -by subbuffering or merging. This function will always return a -buffer with a single memory region. - -Note that no assumptions should be made as to whether certain buffer -flags such as the DISCONT flag are set on the returned buffer, or not. -The caller needs to explicitly set or unset flags that should be set or -unset. - -Since 1.6 this will also copy over all GstMeta of the input buffers except -for meta with the %GST_META_FLAG_POOLED flag or with the "memory" tag. - -Caller owns a reference to the returned buffer. gst_buffer_unref() after -usage. - -Free-function: gst_buffer_unref - - - a #GstBuffer containing the first - @nbytes of the adapter, or %NULL if @nbytes bytes are not available. - gst_buffer_unref() when no longer needed. - - - - - a #GstAdapter - - - - the number of bytes to take - - - - - - Returns a #GstBuffer containing the first @nbytes of the @adapter. -The returned bytes will be flushed from the adapter. This function -is potentially more performant than gst_adapter_take_buffer() since -it can reuse the memory in pushed buffers by subbuffering or -merging. Unlike gst_adapter_take_buffer(), the returned buffer may -be composed of multiple non-contiguous #GstMemory objects, no -copies are made. - -Note that no assumptions should be made as to whether certain buffer -flags such as the DISCONT flag are set on the returned buffer, or not. -The caller needs to explicitly set or unset flags that should be set or -unset. - -This will also copy over all GstMeta of the input buffers except -for meta with the %GST_META_FLAG_POOLED flag or with the "memory" tag. - -This function can return buffer up to the return value of -gst_adapter_available() without making copies if possible. - -Caller owns a reference to the returned buffer. gst_buffer_unref() after -usage. - -Free-function: gst_buffer_unref - - - a #GstBuffer containing the first - @nbytes of the adapter, or %NULL if @nbytes bytes are not available. - gst_buffer_unref() when no longer needed. - - - - - a #GstAdapter - - - - the number of bytes to take - - - - - - Returns a #GstBufferList of buffers containing the first @nbytes bytes of -the @adapter. The returned bytes will be flushed from the adapter. -When the caller can deal with individual buffers, this function is more -performant because no memory should be copied. - -Caller owns the returned list. Call gst_buffer_list_unref() to free -the list after usage. - - - a #GstBufferList of buffers containing - the first @nbytes of the adapter, or %NULL if @nbytes bytes are not - available - - - - - a #GstAdapter - - - - the number of bytes to take - - - - - - Returns a #GList of buffers containing the first @nbytes bytes of the -@adapter. The returned bytes will be flushed from the adapter. -When the caller can deal with individual buffers, this function is more -performant because no memory should be copied. - -Caller owns returned list and contained buffers. gst_buffer_unref() each -buffer in the list before freeing the list after usage. - - - a #GList of - buffers containing the first @nbytes of the adapter, or %NULL if @nbytes - bytes are not available - - - - - - - a #GstAdapter - - - - the number of bytes to take - - - - - - Releases the memory obtained with the last gst_adapter_map(). - - - - - - - a #GstAdapter - - - - - - - - - - Manages a set of pads with the purpose of aggregating their buffers. -Control is given to the subclass when all pads have data. - - * Base class for mixers and muxers. Subclasses should at least implement - the #GstAggregatorClass.aggregate() virtual method. - - * Installs a #GstPadChainFunction, a #GstPadEventFullFunction and a - #GstPadQueryFunction to queue all serialized data packets per sink pad. - Subclasses should not overwrite those, but instead implement - #GstAggregatorClass.sink_event() and #GstAggregatorClass.sink_query() as - needed. - - * When data is queued on all pads, the aggregate vmethod is called. - - * One can peek at the data on any given GstAggregatorPad with the - gst_aggregator_pad_peek_buffer() method, and remove it from the pad - with the gst_aggregator_pad_pop_buffer () method. When a buffer - has been taken with pop_buffer (), a new buffer can be queued - on that pad. - - * If the subclass wishes to push a buffer downstream in its aggregate - implementation, it should do so through the - gst_aggregator_finish_buffer() method. This method will take care - of sending and ordering mandatory events such as stream start, caps - and segment. Buffer lists can also be pushed out with - gst_aggregator_finish_buffer_list(). - - * Same goes for EOS events, which should not be pushed directly by the - subclass, it should instead return GST_FLOW_EOS in its aggregate - implementation. - - * Note that the aggregator logic regarding gap event handling is to turn - these into gap buffers with matching PTS and duration. It will also - flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE - to ease their identification and subsequent processing. - - * Subclasses must use (a subclass of) #GstAggregatorPad for both their - sink and source pads. - See gst_element_class_add_static_pad_template_with_gtype(). - -This class used to live in gst-plugins-bad and was moved to core. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This method will push the provided output buffer downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - - - - - - - The #GstAggregator - - - - the #GstBuffer to push. - - - - - - This method will push the provided output buffer list downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - - - - - - - The #GstAggregator - - - - the #GstBufferList to push. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiates src pad caps with downstream elements. -Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again -if #GstAggregatorClass.negotiate() fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAggregator - - - - - - - - - - - - - - - - - - - - Use this function to determine what input buffers will be aggregated -to produce the next output buffer. This should only be called from -a #GstAggregator::samples-selected handler, and can be used to precisely -control aggregating parameters for a given set of input samples. - - - The sample that is about to be aggregated. It may hold a #GstBuffer - or a #GstBufferList. The contents of its info structure is subclass-dependent, - and documented on a subclass basis. The buffers held by the sample are - not writable. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This method will push the provided output buffer downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - - - - - - - The #GstAggregator - - - - the #GstBuffer to push. - - - - - - This method will push the provided output buffer list downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - - - - - - - The #GstAggregator - - - - the #GstBufferList to push. - - - - - - Lets #GstAggregator sub-classes get the memory @allocator -acquired by the base class and its @params. - -Unref the @allocator after use it. - - - - - - - a #GstAggregator - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - - - the instance of the #GstBufferPool used -by @trans; free it after use it - - - - - a #GstAggregator - - - - - - Retrieves the latency values reported by @self in response to the latency -query, or %GST_CLOCK_TIME_NONE if there is not live source connected and the element -will not wait for the clock. - -Typically only called by subclasses. - - - The latency or %GST_CLOCK_TIME_NONE if the element does not sync - - - - - a #GstAggregator - - - - - - Negotiates src pad caps with downstream elements. -Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again -if #GstAggregatorClass.negotiate() fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAggregator - - - - - - Use this function to determine what input buffers will be aggregated -to produce the next output buffer. This should only be called from -a #GstAggregator::samples-selected handler, and can be used to precisely -control aggregating parameters for a given set of input samples. - - - The sample that is about to be aggregated. It may hold a #GstBuffer - or a #GstBufferList. The contents of its info structure is subclass-dependent, - and documented on a subclass basis. The buffers held by the sample are - not writable. - - - - - - - - - - - - - Subclasses should call this when they have prepared the -buffers they will aggregate for each of their sink pads, but -before using any of the properties of the pads that govern -*how* aggregation should be performed, for example z-index -for video aggregators. - -If gst_aggregator_update_segment() is used by the subclass, -it MUST be called before gst_aggregator_selected_samples(). - -This function MUST only be called from the #GstAggregatorClass::aggregate() -function. - - - - - - - - - - The presentation timestamp of the next output buffer - - - - The decoding timestamp of the next output buffer - - - - The duration of the next output buffer - - - - a #GstStructure containing additional information - - - - - - Lets #GstAggregator sub-classes tell the baseclass what their internal -latency is. Will also post a LATENCY message on the bus so the pipeline -can reconfigure its global latency. - - - - - - - a #GstAggregator - - - - minimum latency - - - - maximum latency - - - - - - Sets the caps to be used on the src pad. - - - - - - - The #GstAggregator - - - - The #GstCaps to set on the src pad. - - - - - - This is a simple #GstAggregatorClass.get_next_time() implementation that -just looks at the #GstSegment on the srcpad of the aggregator and bases -the next time on the running time there. - -This is the desired behaviour in most cases where you have a live source -and you have a dead line based aggregator subclass. - - - The running time based on the position - - - - - A #GstAggregator - - - - - - Subclasses should use this to update the segment on their -source pad, instead of directly pushing new segment events -downstream. - -Subclasses MUST call this before gst_aggregator_selected_samples(), -if it is used at all. - - - - - - - - - - - - - - - Enables the emission of signals such as #GstAggregator::samples-selected - - - - - - - Force minimum upstream latency (in nanoseconds). When sources with a -higher latency are expected to be plugged in dynamically after the -aggregator has started playing, this allows overriding the minimum -latency reported by the initial source(s). This is only taken into -account when larger than the actually reported minimum latency. - - - - - - - - - - - - - the aggregator's source pad - - - - - - - - - - - - Signals that the #GstAggregator subclass has selected the next set -of input samples it will aggregate. Handlers may call -gst_aggregator_peek_next_sample() at that point. - - - - - - The #GstSegment the next output buffer is part of - - - - The presentation timestamp of the next output buffer - - - - The decoding timestamp of the next output buffer - - - - The duration of the next output buffer - - - - a #GstStructure containing additional information - - - - - - - The aggregator base class will handle in a thread-safe way all manners of -concurrent flushes, seeks, pad additions and removals, leaving to the -subclass the responsibility of clipping buffers, and aggregating buffers in -the way the implementor sees fit. - -It will also take care of event ordering (stream-start, segment, eos). - -Basically, a simple implementation will override @aggregate, and call -_finish_buffer from inside that function. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstAggregator - - - - the #GstBuffer to push. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstAggregator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstAggregator - - - - the #GstBufferList to push. - - - - - - - - - - The sample that is about to be aggregated. It may hold a #GstBuffer - or a #GstBufferList. The contents of its info structure is subclass-dependent, - and documented on a subclass basis. The buffers held by the sample are - not writable. - - - - - - - - - - - - - - - - - - - - Pads managed by a #GstAggregator subclass. - -This class used to live in gst-plugins-bad and was moved to core. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Drop the buffer currently queued in @pad. - - - TRUE if there was a buffer queued in @pad, or FALSE if not. - - - - - the pad where to drop any pending buffer - - - - - - This checks if a pad has a buffer available that will be returned by -a call to gst_aggregator_pad_peek_buffer() or -gst_aggregator_pad_pop_buffer(). - - - %TRUE if the pad has a buffer available as the next thing. - - - - - the pad to check the buffer on - - - - - - - - %TRUE if the pad is EOS, otherwise %FALSE. - - - - - an aggregator pad - - - - - - - - A reference to the buffer in @pad or -NULL if no buffer was queued. You should unref the buffer after -usage. - - - - - the pad to get buffer from - - - - - - Steal the ref to the buffer currently queued in @pad. - - - The buffer in @pad or NULL if no buffer was - queued. You should unref the buffer after usage. - - - - - the pad to get buffer from - - - - - - Enables the emission of signals such as #GstAggregatorPad::buffer-consumed - - - - - - - last segment received. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Start at running time 0. - - - Start at the running time of -the first buffer that is received. - - - Start at the running time -selected by the `start-time` property. - - - - - - - - - - - - - - - - - - - - - - - - - Obtains current drain status (ie. whether EOS has been received and -the parser is now processing the frames at the end of the stream) - - - - base parse instance - - - - - - - - - - - - - - - - - - - - Obtains current sync status. - - - - base parse instance - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - base parse instance - - - - - Gives the pointer to the source #GstPad object of the element. - - - - base parse instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gives the pointer to the #GstPad object of the element. - - - - base sink instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gives the pointer to the #GstPad object of the element. - - - - base source instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the templates for the sink pad. - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - base transform instance - - - - - The name of the templates for the source pad. - - - - - Gives the pointer to the source #GstPad object of the element. - - - - base transform instance - - - - - - - - - - - - A #GstBitReader must be initialized with this macro, before it can be -used. This macro can used be to initialize a variable, but it cannot -be assigned to a variable. In that case you have to use -gst_bit_reader_init(). - - - - Data from which the #GstBitReader should read - - - Size of @data in bytes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GstByteReader must be initialized with this macro, before it can be -used. This macro can used be to initialize a variable, but it cannot -be assigned to a variable. In that case you have to use -gst_byte_reader_init(). - - - - Data from which the #GstByteReader should read - - - Size of @data in bytes - - - - - - - - - - - - This base class is for parser elements that process data and splits it -into separate audio/video/whatever frames. - -It provides for: - - * provides one sink pad and one source pad - * handles state changes - * can operate in pull mode or push mode - * handles seeking in both modes - * handles events (SEGMENT/EOS/FLUSH) - * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) - * handles flushing - -The purpose of this base class is to provide the basic functionality of -a parser and share a lot of rather complex code. - -# Description of the parsing mechanism: - -## Set-up phase - - * #GstBaseParse calls #GstBaseParseClass.start() to inform subclass - that data processing is about to start now. - - * #GstBaseParse class calls #GstBaseParseClass.set_sink_caps() to - inform the subclass about incoming sinkpad caps. Subclass could - already set the srcpad caps accordingly, but this might be delayed - until calling gst_base_parse_finish_frame() with a non-queued frame. - - * At least at this point subclass needs to tell the #GstBaseParse class - how big data chunks it wants to receive (minimum frame size ). It can - do this with gst_base_parse_set_min_frame_size(). - - * #GstBaseParse class sets up appropriate data passing mode (pull/push) - and starts to process the data. - -## Parsing phase - - * #GstBaseParse gathers at least min_frame_size bytes of data either - by pulling it from upstream or collecting buffers in an internal - #GstAdapter. - - * A buffer of (at least) min_frame_size bytes is passed to subclass - with #GstBaseParseClass.handle_frame(). Subclass checks the contents - and can optionally return #GST_FLOW_OK along with an amount of data - to be skipped to find a valid frame (which will result in a - subsequent DISCONT). If, otherwise, the buffer does not hold a - complete frame, #GstBaseParseClass.handle_frame() can merely return - and will be called again when additional data is available. In push - mode this amounts to an additional input buffer (thus minimal - additional latency), in pull mode this amounts to some arbitrary - reasonable buffer size increase. - - Of course, gst_base_parse_set_min_frame_size() could also be used if - a very specific known amount of additional data is required. If, - however, the buffer holds a complete valid frame, it can pass the - size of this frame to gst_base_parse_finish_frame(). - - If acting as a converter, it can also merely indicate consumed input - data while simultaneously providing custom output data. Note that - baseclass performs some processing (such as tracking overall consumed - data rate versus duration) for each finished frame, but other state - is only updated upon each call to #GstBaseParseClass.handle_frame() - (such as tracking upstream input timestamp). - - Subclass is also responsible for setting the buffer metadata - (e.g. buffer timestamp and duration, or keyframe if applicable). - (although the latter can also be done by #GstBaseParse if it is - appropriately configured, see below). Frame is provided with - timestamp derived from upstream (as much as generally possible), - duration obtained from configuration (see below), and offset - if meaningful (in pull mode). - - Note that #GstBaseParseClass.handle_frame() might receive any small - amount of input data when leftover data is being drained (e.g. at - EOS). - - * As part of finish frame processing, just prior to actually pushing - the buffer in question, it is passed to - #GstBaseParseClass.pre_push_frame() which gives subclass yet one last - chance to examine buffer metadata, or to send some custom (tag) - events, or to perform custom (segment) filtering. - - * During the parsing process #GstBaseParseClass will handle both srcpad - and sinkpad events. They will be passed to subclass if - #GstBaseParseClass.sink_event() or #GstBaseParseClass.src_event() - implementations have been provided. - -## Shutdown phase - -* #GstBaseParse class calls #GstBaseParseClass.stop() to inform the - subclass that data parsing will be stopped. - -Subclass is responsible for providing pad template caps for source and -sink pads. The pads need to be named "sink" and "src". It also needs to -set the fixed caps on srcpad, when the format is ensured (e.g. when -base class calls subclass' #GstBaseParseClass.set_sink_caps() function). - -This base class uses %GST_FORMAT_DEFAULT as a meaning of frames. So, -subclass conversion routine needs to know that conversion from -%GST_FORMAT_TIME to %GST_FORMAT_DEFAULT must return the -frame number that can be found from the given byte position. - -#GstBaseParse uses subclasses conversion methods also for seeking (or -otherwise uses its own default one, see also below). - -Subclass @start and @stop functions will be called to inform the beginning -and end of data processing. - -Things that subclass need to take care of: - -* Provide pad templates -* Fixate the source pad caps when appropriate -* Inform base class how big data chunks should be retrieved. This is - done with gst_base_parse_set_min_frame_size() function. -* Examine data chunks passed to subclass with - #GstBaseParseClass.handle_frame() and pass proper frame(s) to - gst_base_parse_finish_frame(), and setting src pad caps and timestamps - on frame. -* Provide conversion functions -* Update the duration information with gst_base_parse_set_duration() -* Optionally passthrough using gst_base_parse_set_passthrough() -* Configure various baseparse parameters using - gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable() - and gst_base_parse_set_frame_rate(). - -* In particular, if subclass is unable to determine a duration, but - parsing (or specs) yields a frames per seconds rate, then this can be - provided to #GstBaseParse to enable it to cater for buffer time - metadata (which will be taken from upstream as much as - possible). Internally keeping track of frame durations and respective - sizes that have been pushed provides #GstBaseParse with an estimated - bitrate. A default #GstBaseParseClass.convert() (used if not - overridden) will then use these rates to perform obvious conversions. - These rates are also used to update (estimated) duration at regular - frame intervals. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Adds an entry to the index associating @offset to @ts. It is recommended -to only add keyframe entries. @force allows to bypass checks, such as -whether the stream is (upstream) seekable, another entry is already "close" -to the new entry, etc. - - - #gboolean indicating whether entry was added - - - - - #GstBaseParse. - - - - offset of entry - - - - timestamp associated with offset - - - - whether entry refers to keyframe - - - - add entry disregarding sanity checks - - - - - - Default implementation of #GstBaseParseClass.convert(). - - - %TRUE if conversion was successful. - - - - - #GstBaseParse. - - - - #GstFormat describing the source format. - - - - Source value to be converted. - - - - #GstFormat defining the converted format. - - - - Pointer where the conversion result will be put. - - - - - - Drains the adapter until it is empty. It decreases the min_frame_size to -match the current adapter size and calls chain method until the adapter -is emptied or chain returns with error. - - - - - - - a #GstBaseParse - - - - - - Collects parsed data and pushes this downstream. -Source pad caps must be set when this is called. - -If @frame's out_buffer is set, that will be used as subsequent frame data. -Otherwise, @size samples will be taken from the input and used for output, -and the output's metadata (timestamps etc) will be taken as (optionally) -set by the subclass on @frame's (input) buffer (which is otherwise -ignored for any but the above purpose/information). - -Note that the latter buffer is invalidated by this call, whereas the -caller retains ownership of @frame. - - - a #GstFlowReturn that should be escalated to caller (of caller) - - - - - a #GstBaseParse - - - - a #GstBaseParseFrame - - - - consumed input data represented by frame - - - - - - Sets the parser subclass's tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with gst_base_parse_merge_tags(). - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - - - - - - - a #GstBaseParse - - - - a #GstTagList to merge, or NULL to unset - previously-set tags - - - - the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE - - - - - - Pushes the frame's buffer downstream, sends any pending events and -does some timestamp and segment handling. Takes ownership of -frame's buffer, though caller retains ownership of @frame. - -This must be called with sinkpad STREAM_LOCK held. - - - #GstFlowReturn - - - - - #GstBaseParse. - - - - a #GstBaseParseFrame - - - - - - Optionally sets the average bitrate detected in media (if non-zero), -e.g. based on metadata, as it will be posted to the application. - -By default, announced average bitrate is estimated. The average bitrate -is used to estimate the total duration of the stream and to estimate -a seek position, if there's no index and the format is syncable -(see gst_base_parse_set_syncable()). - - - - - - - #GstBaseParse. - - - - average bitrate in bits/second - - - - - - Sets the duration of the currently playing media. Subclass can use this -when it is able to determine duration and/or notices a change in the media -duration. Alternatively, if @interval is non-zero (default), then stream -duration is determined based on estimated bitrate, and updated every @interval -frames. - - - - - - - #GstBaseParse. - - - - #GstFormat. - - - - duration value. - - - - how often to update the duration estimate based on bitrate, or 0. - - - - - - If frames per second is configured, parser can take care of buffer duration -and timestamping. When performing segment clipping, or seeking to a specific -location, a corresponding decoder might need an initial @lead_in and a -following @lead_out number of frames to ensure the desired segment is -entirely filled upon decoding. - - - - - - - the #GstBaseParse to set - - - - frames per second (numerator). - - - - frames per second (denominator). - - - - frames needed before a segment for subsequent decode - - - - frames needed after a segment - - - - - - Set if frames carry timing information which the subclass can (generally) -parse and provide. In particular, intrinsic (rather than estimated) time -can be obtained following a seek. - - - - - - - a #GstBaseParse - - - - whether frames carry timing information - - - - - - By default, the base class might try to infer PTS from DTS and vice -versa. While this is generally correct for audio data, it may not -be otherwise. Sub-classes implementing such formats should disable -timestamp inferring. - - - - - - - a #GstBaseParse - - - - %TRUE if parser should infer DTS/PTS from each other - - - - - - Sets the minimum and maximum (which may likely be equal) latency introduced -by the parsing process. If there is such a latency, which depends on the -particular parsing of the format, it typically corresponds to 1 frame duration. - - - - - - - a #GstBaseParse - - - - minimum parse latency - - - - maximum parse latency - - - - - - Subclass can use this function to tell the base class that it needs to -be given buffers of at least @min_size bytes. - - - - - - - #GstBaseParse. - - - - Minimum size in bytes of the data that this base class should - give to subclass. - - - - - - Set if the nature of the format or configuration does not allow (much) -parsing, and the parser should operate in passthrough mode (which only -applies when operating in push mode). That is, incoming buffers are -pushed through unmodified, i.e. no #GstBaseParseClass.handle_frame() -will be invoked, but #GstBaseParseClass.pre_push_frame() will still be -invoked, so subclass can perform as much or as little is appropriate for -passthrough semantics in #GstBaseParseClass.pre_push_frame(). - - - - - - - a #GstBaseParse - - - - %TRUE if parser should run in passthrough mode - - - - - - By default, the base class will guess PTS timestamps using a simple -interpolation (previous timestamp + duration), which is incorrect for -data streams with reordering, where PTS can go backward. Sub-classes -implementing such formats should disable PTS interpolation. - - - - - - - a #GstBaseParse - - - - %TRUE if parser should interpolate PTS timestamps - - - - - - Set if frame starts can be identified. This is set by default and -determines whether seeking based on bitrate averages -is possible for a format/stream. - - - - - - - a #GstBaseParse - - - - set if frame starts can be identified - - - - - - This function should only be called from a @handle_frame implementation. - -#GstBaseParse creates initial timestamps for frames by using the last -timestamp seen in the stream before the frame starts. In certain -cases, the correct timestamps will occur in the stream after the -start of the frame, but before the start of the actual picture data. -This function can be used to set the timestamps based on the offset -into the frame data that the picture starts. - - - - - - - a #GstBaseParse - - - - offset into current buffer - - - - - - If set to %TRUE, baseparse will unconditionally force parsing of the -incoming data. This can be required in the rare cases where the incoming -side-data (caps, pts, dts, ...) is not trusted by the user and wants to -force validation and parsing of the incoming data. -If set to %FALSE, decision of whether to parse the data or not is up to -the implementation (standard behaviour). - - - - the parent element. - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum @handle_frame needs to be overridden. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Frame (context) data passed to each frame parsing virtual methods. In -addition to providing the data to be checked for a valid frame or an already -identified frame, it conveys additional metadata or control information -from and to the subclass w.r.t. the particular frame in question (rather -than global parameters). Some of these may apply to each parsing stage, others -only to some a particular one. These parameters are effectively zeroed at start -of each frame's processing, i.e. parsing virtual method invocation sequence. - - - input data to be parsed for frames. - - - - output data. - - - - a combination of input and output #GstBaseParseFrameFlags that - convey additional context to subclass or allow subclass to tune - subsequent #GstBaseParse actions. - - - - media specific offset of input frame - Note that a converter may have a different one on the frame's buffer. - - - - subclass can set this to indicates the metadata overhead - for the given frame, which is then used to enable more accurate bitrate - computations. If this is -1, it is assumed that this frame should be - skipped in bitrate calculation. - - - - - - - - - - - - - - - - - - - - Allocates a new #GstBaseParseFrame. This function is mainly for bindings, -elements written in C should usually allocate the frame on the stack and -then use gst_base_parse_frame_init() to initialise it. - - - a newly-allocated #GstBaseParseFrame. Free with - gst_base_parse_frame_free() when no longer needed. - - - - - a #GstBuffer - - - - the flags - - - - number of bytes in this frame which should be counted as - metadata overhead, ie. not used to calculate the average bitrate. - Set to -1 to mark the entire frame as metadata. If in doubt, set to 0. - - - - - - Copies a #GstBaseParseFrame. - - - A copy of @frame - - - - - a #GstBaseParseFrame - - - - - - Frees the provided @frame. - - - - - - - A #GstBaseParseFrame - - - - - - Sets a #GstBaseParseFrame to initial state. Currently this means -all public fields are zero-ed and a private flag is set to make -sure gst_base_parse_frame_free() only frees the contents but not -the actual frame. Use this function to initialise a #GstBaseParseFrame -allocated on the stack. - - - - - - - #GstBaseParseFrame. - - - - - - - Flags to be used in a #GstBaseParseFrame. - - - no flag - - - set by baseclass if current frame - is passed for processing to the subclass for the first time - (and not set on subsequent calls with same data). - - - set to indicate this buffer should not be - counted as frame, e.g. if this frame is dependent on a previous one. - As it is not counted as a frame, bitrate increases but frame to time - conversions are maintained. - - - @pre_push_frame can set this to indicate - that regular segment clipping can still be performed (as opposed to - any custom one having been done). - - - indicates to @finish_frame that the - the frame should be dropped (and might be handled internally by subclass) - - - indicates to @finish_frame that the - the frame should be queued for now and processed fully later - when the first non-queued frame is finished - - - - - - - #GstBaseSink is the base class for sink elements in GStreamer, such as -xvimagesink or filesink. It is a layer on top of #GstElement that provides a -simplified interface to plugin writers. #GstBaseSink handles many details -for you, for example: preroll, clock synchronization, state changes, -activation in push or pull mode, and queries. - -In most cases, when writing sink elements, there is no need to implement -class methods from #GstElement or to set functions on pads, because the -#GstBaseSink infrastructure should be sufficient. - -#GstBaseSink provides support for exactly one sink pad, which should be -named "sink". A sink implementation (subclass of #GstBaseSink) should -install a pad template in its class_init function, like so: -|[<!-- language="C" --> -static void -my_element_class_init (GstMyElementClass *klass) -{ - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - - // sinktemplate should be a #GstStaticPadTemplate with direction - // %GST_PAD_SINK and name "sink" - gst_element_class_add_static_pad_template (gstelement_class, &amp;sinktemplate); - - gst_element_class_set_static_metadata (gstelement_class, - "Sink name", - "Sink", - "My Sink element", - "The author <my.sink@my.email>"); -} -]| - -#GstBaseSink will handle the prerolling correctly. This means that it will -return %GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first -buffer arrives in this element. The base class will call the -#GstBaseSinkClass.preroll() vmethod with this preroll buffer and will then -commit the state change to the next asynchronously pending state. - -When the element is set to PLAYING, #GstBaseSink will synchronise on the -clock using the times returned from #GstBaseSinkClass.get_times(). If this -function returns %GST_CLOCK_TIME_NONE for the start time, no synchronisation -will be done. Synchronisation can be disabled entirely by setting the object -#GstBaseSink:sync property to %FALSE. - -After synchronisation the virtual method #GstBaseSinkClass.render() will be -called. Subclasses should minimally implement this method. - -Subclasses that synchronise on the clock in the #GstBaseSinkClass.render() -method are supported as well. These classes typically receive a buffer in -the render method and can then potentially block on the clock while -rendering. A typical example is an audiosink. -These subclasses can use gst_base_sink_wait_preroll() to perform the -blocking wait. - -Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait -for the clock to reach the time indicated by the stop time of the last -#GstBaseSinkClass.get_times() call before posting an EOS message. When the -element receives EOS in PAUSED, preroll completes, the event is queued and an -EOS message is posted when going to PLAYING. - -#GstBaseSink will internally use the %GST_EVENT_SEGMENT events to schedule -synchronisation and clipping of buffers. Buffers that fall completely outside -of the current segment are dropped. Buffers that fall partially in the -segment are rendered (and prerolled). Subclasses should do any subbuffer -clipping themselves when needed. - -#GstBaseSink will by default report the current playback position in -%GST_FORMAT_TIME based on the current clock time and segment information. -If no clock has been set on the element, the query will be forwarded -upstream. - -The #GstBaseSinkClass.set_caps() function will be called when the subclass -should configure itself to process a specific media type. - -The #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() virtual methods -will be called when resources should be allocated. Any -#GstBaseSinkClass.preroll(), #GstBaseSinkClass.render() and -#GstBaseSinkClass.set_caps() function will be called between the -#GstBaseSinkClass.start() and #GstBaseSinkClass.stop() calls. - -The #GstBaseSinkClass.event() virtual method will be called when an event is -received by #GstBaseSink. Normally this method should only be overridden by -very specific elements (such as file sinks) which need to handle the -newsegment event specially. - -The #GstBaseSinkClass.unlock() method is called when the elements should -unblock any blocking operations they perform in the -#GstBaseSinkClass.render() method. This is mostly useful when the -#GstBaseSinkClass.render() method performs a blocking write on a file -descriptor, for example. - -The #GstBaseSink:max-lateness property affects how the sink deals with -buffers that arrive too late in the sink. A buffer arrives too late in the -sink when the presentation time (as a combination of the last segment, buffer -timestamp and element base_time) plus the duration is before the current -time of the clock. -If the frame is later than max-lateness, the sink will drop the buffer -without calling the render method. -This feature is disabled if sync is disabled, the -#GstBaseSinkClass.get_times() method does not return a valid start time or -max-lateness is set to -1 (the default). -Subclasses can use gst_base_sink_set_max_lateness() to configure the -max-lateness value. - -The #GstBaseSink:qos property will enable the quality-of-service features of -the basesink which gather statistics about the real-time performance of the -clock synchronisation. For each buffer received in the sink, statistics are -gathered and a QOS event is sent upstream with these numbers. This -information can then be used by upstream elements to reduce their processing -rate, for example. - -The #GstBaseSink:async property can be used to instruct the sink to never -perform an ASYNC state change. This feature is mostly usable when dealing -with non-synchronized streams or sparse streams. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - If the @sink spawns its own thread for pulling buffers from upstream it -should call this method after it has pulled a buffer. If the element needed -to preroll, this function will perform the preroll and will then block -until the element state is changed. - -This function should be called with the PREROLL_LOCK held. - - - %GST_FLOW_OK if the preroll completed and processing can -continue. Any other return value should be returned from the render vmethod. - - - - - the sink - - - - the mini object that caused the preroll - - - - - - Get the number of bytes that the sink will pull when it is operating in pull -mode. - - - the number of bytes @sink will pull in pull mode. - - - - - a #GstBaseSink - - - - - - Checks if @sink is currently configured to drop buffers which are outside -the current segment - - - %TRUE if the sink is configured to drop buffers outside the -current segment. - - - - - the sink - - - - - - Get the last sample that arrived in the sink and was used for preroll or for -rendering. This property can be used to generate thumbnails. - -The #GstCaps on the sample can be used to determine the type of the buffer. - -Free-function: gst_sample_unref - - - a #GstSample. gst_sample_unref() after - usage. This function returns %NULL when no buffer has arrived in the - sink yet or when the sink is not in PAUSED or PLAYING. - - - - - the sink - - - - - - Get the currently configured latency. - - - The configured latency. - - - - - the sink - - - - - - Get the maximum amount of bits per second that the sink will render. - - - the maximum number of bits per second @sink will render. - - - - - a #GstBaseSink - - - - - - Gets the max lateness value. See gst_base_sink_set_max_lateness() for -more details. - - - The maximum time in nanoseconds that a buffer can be late -before it is dropped and not rendered. A value of -1 means an -unlimited time. - - - - - the sink - - - - - - Get the processing deadline of @sink. see -gst_base_sink_set_processing_deadline() for more information about -the processing deadline. - - - the processing deadline - - - - - a #GstBaseSink - - - - - - Get the render delay of @sink. see gst_base_sink_set_render_delay() for more -information about the render delay. - - - the render delay of @sink. - - - - - a #GstBaseSink - - - - - - Return various #GstBaseSink statistics. This function returns a #GstStructure -with name `application/x-gst-base-sink-stats` with the following fields: - -- "average-rate" G_TYPE_DOUBLE average frame rate -- "dropped" G_TYPE_UINT64 Number of dropped frames -- "rendered" G_TYPE_UINT64 Number of rendered frames - - - pointer to #GstStructure - - - - - #GstBaseSink - - - - - - Checks if @sink is currently configured to synchronize against the -clock. - - - %TRUE if the sink is configured to synchronize against the clock. - - - - - the sink - - - - - - Get the time that will be inserted between frames to control the -maximum buffers per second. - - - the number of nanoseconds @sink will put between frames. - - - - - a #GstBaseSink - - - - - - Get the synchronisation offset of @sink. - - - The synchronisation offset. - - - - - the sink - - - - - - Checks if @sink is currently configured to perform asynchronous state -changes to PAUSED. - - - %TRUE if the sink is configured to perform asynchronous state -changes. - - - - - the sink - - - - - - Checks if @sink is currently configured to store the last received sample in -the last-sample property. - - - %TRUE if the sink is configured to store the last received sample. - - - - - the sink - - - - - - Checks if @sink is currently configured to send Quality-of-Service events -upstream. - - - %TRUE if the sink is configured to perform Quality-of-Service. - - - - - the sink - - - - - - Query the sink for the latency parameters. The latency will be queried from -the upstream elements. @live will be %TRUE if @sink is configured to -synchronize against the clock. @upstream_live will be %TRUE if an upstream -element is live. - -If both @live and @upstream_live are %TRUE, the sink will want to compensate -for the latency introduced by the upstream elements by setting the -@min_latency to a strictly positive value. - -This function is mostly used by subclasses. - - - %TRUE if the query succeeded. - - - - - the sink - - - - if the sink is live - - - - if an upstream element is live - - - - the min latency of the upstream elements - - - - the max latency of the upstream elements - - - - - - Configures @sink to perform all state changes asynchronously. When async is -disabled, the sink will immediately go to PAUSED instead of waiting for a -preroll buffer. This feature is useful if the sink does not synchronize -against the clock or when it is dealing with sparse streams. - - - - - - - the sink - - - - the new async value. - - - - - - Set the number of bytes that the sink will pull when it is operating in pull -mode. - - - - - - - a #GstBaseSink - - - - the blocksize in bytes - - - - - - Configure @sink to drop buffers which are outside the current segment - - - - - - - the sink - - - - drop buffers outside the segment - - - - - - Configures @sink to store the last received sample in the last-sample -property. - - - - - - - the sink - - - - the new enable-last-sample value. - - - - - - Set the maximum amount of bits per second that the sink will render. - - - - - - - a #GstBaseSink - - - - the max_bitrate in bits per second - - - - - - Sets the new max lateness value to @max_lateness. This value is -used to decide if a buffer should be dropped or not based on the -buffer timestamp and the current clock time. A value of -1 means -an unlimited time. - - - - - - - the sink - - - - the new max lateness value. - - - - - - Maximum amount of time (in nanoseconds) that the pipeline can take -for processing the buffer. This is added to the latency of live -pipelines. - -This function is usually called by subclasses. - - - - - - - a #GstBaseSink - - - - the new processing deadline in nanoseconds. - - - - - - Configures @sink to send Quality-of-Service events upstream. - - - - - - - the sink - - - - the new qos value. - - - - - - Set the render delay in @sink to @delay. The render delay is the time -between actual rendering of a buffer and its synchronisation time. Some -devices might delay media rendering which can be compensated for with this -function. - -After calling this function, this sink will report additional latency and -other sinks will adjust their latency to delay the rendering of their media. - -This function is usually called by subclasses. - - - - - - - a #GstBaseSink - - - - the new delay - - - - - - Configures @sink to synchronize on the clock or not. When -@sync is %FALSE, incoming samples will be played as fast as -possible. If @sync is %TRUE, the timestamps of the incoming -buffers will be used to schedule the exact render time of its -contents. - - - - - - - the sink - - - - the new sync value. - - - - - - Set the time that will be inserted between rendered buffers. This -can be used to control the maximum buffers per second that the sink -will render. - - - - - - - a #GstBaseSink - - - - the throttle time in nanoseconds - - - - - - Adjust the synchronisation of @sink with @offset. A negative value will -render buffers earlier than their timestamp. A positive value will delay -rendering. This function can be used to fix playback of badly timestamped -buffers. - - - - - - - the sink - - - - the new offset - - - - - - This function will wait for preroll to complete and will then block until @time -is reached. It is usually called by subclasses that use their own internal -synchronisation but want to let some synchronization (like EOS) be handled -by the base class. - -This function should only be called with the PREROLL_LOCK held (like when -receiving an EOS event in the ::event vmethod or when handling buffers in -::render). - -The @time argument should be the running_time of when the timeout should happen -and will be adjusted with any latency and offset configured in the sink. - - - #GstFlowReturn - - - - - the sink - - - - the running_time to be reached - - - - the jitter to be filled with time diff, or %NULL - - - - - - This function will block until @time is reached. It is usually called by -subclasses that use their own internal synchronisation. - -If @time is not valid, no synchronisation is done and %GST_CLOCK_BADTIME is -returned. Likewise, if synchronisation is disabled in the element or there -is no clock, no synchronisation is done and %GST_CLOCK_BADTIME is returned. - -This function should only be called with the PREROLL_LOCK held, like when -receiving an EOS event in the #GstBaseSinkClass.event() vmethod or when -receiving a buffer in -the #GstBaseSinkClass.render() vmethod. - -The @time argument should be the running_time of when this method should -return and is not adjusted with any latency or offset configured in the -sink. - - - #GstClockReturn - - - - - the sink - - - - the running_time to be reached - - - - the jitter to be filled with time diff, or %NULL - - - - - - If the #GstBaseSinkClass.render() method performs its own synchronisation -against the clock it must unblock when going from PLAYING to the PAUSED state -and call this method before continuing to render the remaining data. - -If the #GstBaseSinkClass.render() method can block on something else than -the clock, it must also be ready to unblock immediately on -the #GstBaseSinkClass.unlock() method and cause the -#GstBaseSinkClass.render() method to immediately call this function. -In this case, the subclass must be prepared to continue rendering where it -left off if this function returns %GST_FLOW_OK. - -This function will block until a state change to PLAYING happens (in which -case this function returns %GST_FLOW_OK) or the processing must be stopped due -to a state change to READY or a FLUSH event (in which case this function -returns %GST_FLOW_FLUSHING). - -This function should only be called with the PREROLL_LOCK held, like in the -render function. - - - %GST_FLOW_OK if the preroll completed and processing can -continue. Any other return value should be returned from the render vmethod. - - - - - the sink - - - - - - If set to %TRUE, the basesink will perform asynchronous state changes. -When set to %FALSE, the sink will not signal the parent when it prerolls. -Use this option when dealing with sparse streams or when synchronisation is -not required. - - - - The amount of bytes to pull when operating in pull mode. - - - - Enable the last-sample property. If %FALSE, basesink doesn't keep a -reference to the last buffer arrived and the last-sample property is always -set to %NULL. This can be useful if you need buffers to be released as soon -as possible, eg. if you're using a buffer pool. - - - - The last buffer that arrived in the sink and was used for preroll or for -rendering. This property can be used to generate thumbnails. This property -can be %NULL when the sink has not yet received a buffer. - - - - Control the maximum amount of bits that will be rendered per second. -Setting this property to a value bigger than 0 will make the sink delay -rendering of the buffers when it would exceed to max-bitrate. - - - - - - - Maximum amount of time (in nanoseconds) that the pipeline can take -for processing the buffer. This is added to the latency of live -pipelines. - - - - - - - The additional delay between synchronisation and actual rendering of the -media. This property will add additional latency to the device in order to -make other sinks compensate for the delay. - - - - Various #GstBaseSink statistics. This property returns a #GstStructure -with name `application/x-gst-base-sink-stats` with the following fields: - -- "average-rate" G_TYPE_DOUBLE average frame rate -- "dropped" G_TYPE_UINT64 Number of dropped frames -- "rendered" G_TYPE_UINT64 Number of rendered frames - - - - - - - The time to insert between buffers. This property can be used to control -the maximum amount of buffers per second to render. Setting this property -to a value bigger than 0 will make the sink create THROTTLE QoS events. - - - - Controls the final synchronisation, a negative value will render the buffer -earlier while a positive value delays playback. This property can be -used to fix synchronisation in bad files. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At the minimum, the @render method should be overridden to -output/present buffers. - - - Element parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This is a generic base class for source elements. The following -types of sources are supported: - - * random access sources like files - * seekable sources - * live sources - -The source can be configured to operate in any #GstFormat with the -gst_base_src_set_format() method. The currently set format determines -the format of the internal #GstSegment and any %GST_EVENT_SEGMENT -events. The default format for #GstBaseSrc is %GST_FORMAT_BYTES. - -#GstBaseSrc always supports push mode scheduling. If the following -conditions are met, it also supports pull mode scheduling: - - * The format is set to %GST_FORMAT_BYTES (default). - * #GstBaseSrcClass.is_seekable() returns %TRUE. - -If all the conditions are met for operating in pull mode, #GstBaseSrc is -automatically seekable in push mode as well. The following conditions must -be met to make the element seekable in push mode when the format is not -%GST_FORMAT_BYTES: - -* #GstBaseSrcClass.is_seekable() returns %TRUE. -* #GstBaseSrcClass.query() can convert all supported seek formats to the - internal format as set with gst_base_src_set_format(). -* #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns - %TRUE. - -When the element does not meet the requirements to operate in pull mode, the -offset and length in the #GstBaseSrcClass.create() method should be ignored. -It is recommended to subclass #GstPushSrc instead, in this situation. If the -element can operate in pull mode but only with specific offsets and -lengths, it is allowed to generate an error when the wrong values are passed -to the #GstBaseSrcClass.create() function. - -#GstBaseSrc has support for live sources. Live sources are sources that when -paused discard data, such as audio or video capture devices. A typical live -source also produces data at a fixed rate and thus provides a clock to publish -this rate. -Use gst_base_src_set_live() to activate the live source mode. - -A live source does not produce data in the PAUSED state. This means that the -#GstBaseSrcClass.create() method will not be called in PAUSED but only in -PLAYING. To signal the pipeline that the element will not produce data, the -return value from the READY to PAUSED state will be -%GST_STATE_CHANGE_NO_PREROLL. - -A typical live source will timestamp the buffers it creates with the -current running time of the pipeline. This is one reason why a live source -can only produce data in the PLAYING state, when the clock is actually -distributed and running. - -Live sources that synchronize and block on the clock (an audio source, for -example) can use gst_base_src_wait_playing() when the -#GstBaseSrcClass.create() function was interrupted by a state change to -PAUSED. - -The #GstBaseSrcClass.get_times() method can be used to implement pseudo-live -sources. It only makes sense to implement the #GstBaseSrcClass.get_times() -function if the source is a live source. The #GstBaseSrcClass.get_times() -function should return timestamps starting from 0, as if it were a non-live -source. The base class will make sure that the timestamps are transformed -into the current running_time. The base source will then wait for the -calculated running_time before pushing out the buffer. - -For live sources, the base class will by default report a latency of 0. -For pseudo live sources, the base class will by default measure the difference -between the first buffer timestamp and the start time of get_times and will -report this value as the latency. -Subclasses should override the query function when this behaviour is not -acceptable. - -There is only support in #GstBaseSrc for exactly one source pad, which -should be named "src". A source implementation (subclass of #GstBaseSrc) -should install a pad template in its class_init function, like so: -|[<!-- language="C" --> -static void -my_element_class_init (GstMyElementClass *klass) -{ - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - // srctemplate should be a #GstStaticPadTemplate with direction - // %GST_PAD_SRC and name "src" - gst_element_class_add_static_pad_template (gstelement_class, &amp;srctemplate); - - gst_element_class_set_static_metadata (gstelement_class, - "Source name", - "Source", - "My Source element", - "The author <my.sink@my.email>"); -} -]| - -## Controlled shutdown of live sources in applications - -Applications that record from a live source may want to stop recording -in a controlled way, so that the recording is stopped, but the data -already in the pipeline is processed to the end (remember that many live -sources would go on recording forever otherwise). For that to happen the -application needs to make the source stop recording and send an EOS -event down the pipeline. The application would then wait for an -EOS message posted on the pipeline's bus to know when all data has -been processed and the pipeline can safely be stopped. - -An application may send an EOS event to a source element to make it -perform the EOS logic (send EOS event downstream or post a -%GST_MESSAGE_SEGMENT_DONE on the bus). This can typically be done -with the gst_element_send_event() function on the element or its parent bin. - -After the EOS has been sent to the element, the application should wait for -an EOS message to be posted on the pipeline's bus. Once this EOS message is -received, it may safely shut down the entire pipeline. - - - - - - - - - - - - - - - - - - - - - - - Ask the subclass to create a buffer with @offset and @size, the default -implementation will call alloc and fill. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Called to get the caps to report. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Given @buffer, return @start and @end time when it should be pushed -out. The base class will sync on the clock using these times. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiates src pad caps with downstream elements. -Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again -if #GstBaseSrcClass.negotiate() fails. - -Do not call this in the #GstBaseSrcClass.fill() vmethod. Call this in -#GstBaseSrcClass.create() or in #GstBaseSrcClass.alloc(), _before_ any -buffer is allocated. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - base source instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Set new caps on the basesrc source pad. - - - %TRUE if the caps could be set - - - - - a #GstBaseSrc - - - - a #GstCaps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Lets #GstBaseSrc sub-classes to know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after usage. - - - - - - - a #GstBaseSrc - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - Get the number of bytes that @src will push out with each buffer. - - - the number of bytes pushed with each buffer. - - - - - the source - - - - - - - - the instance of the #GstBufferPool used -by the src; unref it after usage. - - - - - a #GstBaseSrc - - - - - - Query if @src timestamps outgoing buffers based on the current running_time. - - - %TRUE if the base class will automatically timestamp outgoing buffers. - - - - - the source - - - - - - Get the current async behaviour of @src. See also gst_base_src_set_async(). - - - %TRUE if @src is operating in async mode. - - - - - base source instance - - - - - - Check if an element is in live mode. - - - %TRUE if element is in live mode. - - - - - base source instance - - - - - - Negotiates src pad caps with downstream elements. -Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again -if #GstBaseSrcClass.negotiate() fails. - -Do not call this in the #GstBaseSrcClass.fill() vmethod. Call this in -#GstBaseSrcClass.create() or in #GstBaseSrcClass.alloc(), _before_ any -buffer is allocated. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - base source instance - - - - - - Prepare a new seamless segment for emission downstream. This function must -only be called by derived sub-classes, and only from the #GstBaseSrcClass::create function, -as the stream-lock needs to be held. - -The format for the new segment will be the current format of the source, as -configured with gst_base_src_set_format() - Use gst_base_src_new_segment() - - - %TRUE if preparation of the seamless segment succeeded. - - - - - The source - - - - The new start value for the segment - - - - Stop value for the new segment - - - - The new time value for the start of the new segment - - - - - - Prepare a new segment for emission downstream. This function must -only be called by derived sub-classes, and only from the #GstBaseSrcClass::create function, -as the stream-lock needs to be held. - -The format for the @segment must be identical with the current format -of the source, as configured with gst_base_src_set_format(). - -The format of @src must not be %GST_FORMAT_UNDEFINED and the format -should be configured via gst_base_src_set_format() before calling this method. - - - %TRUE if preparation of new segment succeeded. - - - - - a #GstBaseSrc - - - - a pointer to a #GstSegment - - - - - - Query the source for the latency parameters. @live will be %TRUE when @src is -configured as a live source. @min_latency and @max_latency will be set -to the difference between the running time and the timestamp of the first -buffer. - -This function is mostly used by subclasses. - - - %TRUE if the query succeeded. - - - - - the source - - - - if the source is live - - - - the min latency of the source - - - - the max latency of the source - - - - - - Configure async behaviour in @src, no state change will block. The open, -close, start, stop, play and pause virtual methods will be executed in a -different thread and are thus allowed to perform blocking operations. Any -blocking operation should be unblocked with the unlock vmethod. - - - - - - - base source instance - - - - new async mode - - - - - - If @automatic_eos is %TRUE, @src will automatically go EOS if a buffer -after the total size is returned. By default this is %TRUE but sources -that can't return an authoritative size and only know that they're EOS -when trying to read more should set this to %FALSE. - -When @src operates in %GST_FORMAT_TIME, #GstBaseSrc will send an EOS -when a buffer outside of the currently configured segment is pushed if -@automatic_eos is %TRUE. Since 1.16, if @automatic_eos is %FALSE an -EOS will be pushed only when the #GstBaseSrcClass.create() implementation -returns %GST_FLOW_EOS. - - - - - - - base source instance - - - - automatic eos - - - - - - Set the number of bytes that @src will push out with each buffer. When -@blocksize is set to -1, a default length will be used. - - - - - - - the source - - - - the new blocksize in bytes - - - - - - Set new caps on the basesrc source pad. - - - %TRUE if the caps could be set - - - - - a #GstBaseSrc - - - - a #GstCaps - - - - - - Configure @src to automatically timestamp outgoing buffers based on the -current running_time of the pipeline. This property is mostly useful for live -sources. - - - - - - - the source - - - - enable or disable timestamping - - - - - - If not @dynamic, size is only updated when needed, such as when trying to -read past current tracked size. Otherwise, size is checked for upon each -read. - - - - - - - base source instance - - - - new dynamic size mode - - - - - - Sets the default format of the source. This will be the format used -for sending SEGMENT events and for performing seeks. - -If a format of GST_FORMAT_BYTES is set, the element will be able to -operate in pull mode if the #GstBaseSrcClass.is_seekable() returns %TRUE. - -This function must only be called in states < %GST_STATE_PAUSED. - - - - - - - base source instance - - - - the format to use - - - - - - If the element listens to a live source, @live should -be set to %TRUE. - -A live source will not produce data in the PAUSED state and -will therefore not be able to participate in the PREROLL phase -of a pipeline. To signal this fact to the application and the -pipeline, the state change return value of the live source will -be GST_STATE_CHANGE_NO_PREROLL. - - - - - - - base source instance - - - - new live-mode - - - - - - Complete an asynchronous start operation. When the subclass overrides the -start method, it should call gst_base_src_start_complete() when the start -operation completes either from the same thread or from an asynchronous -helper thread. - - - - - - - base source instance - - - - a #GstFlowReturn - - - - - - Wait until the start operation completes. - - - a #GstFlowReturn. - - - - - base source instance - - - - - - Subclasses can call this from their create virtual method implementation -to submit a buffer list to be pushed out later. This is useful in -cases where the create function wants to produce multiple buffers to be -pushed out in one go in form of a #GstBufferList, which can reduce overhead -drastically, especially for packetised inputs (for data streams where -the packetisation/chunking is not important it is usually more efficient -to return larger buffers instead). - -Subclasses that use this function from their create function must return -%GST_FLOW_OK and no buffer from their create virtual method implementation. -If a buffer is returned after a buffer list has also been submitted via this -function the behaviour is undefined. - -Subclasses must only call this function once per create function call and -subclasses must only call this function when the source operates in push -mode. - - - - - - - a #GstBaseSrc - - - - a #GstBufferList - - - - - - If the #GstBaseSrcClass.create() method performs its own synchronisation -against the clock it must unblock when going from PLAYING to the PAUSED state -and call this method before continuing to produce the remaining data. - -This function will block until a state change to PLAYING happens (in which -case this function returns %GST_FLOW_OK) or the processing must be stopped due -to a state change to READY or a FLUSH event (in which case this function -returns %GST_FLOW_FLUSHING). - - - %GST_FLOW_OK if @src is PLAYING and processing can -continue. Any other return value should be returned from the create vmethod. - - - - - the src - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At the minimum, the @create method should be overridden to produce -buffers. - - - Element parent class - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - base source instance - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the caps could be set - - - - - a #GstBaseSrc - - - - a #GstCaps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstElement flags that a basesrc element may have. - - - has source is starting - - - has source been started - - - offset to define more flags - - - - - - - This base class is for filter elements that process data. Elements -that are suitable for implementation using #GstBaseTransform are ones -where the size and caps of the output is known entirely from the input -caps and buffer sizes. These include elements that directly transform -one buffer into another, modify the contents of a buffer in-place, as -well as elements that collate multiple input buffers into one output buffer, -or that expand one input buffer into multiple output buffers. See below -for more concrete use cases. - -It provides for: - -* one sinkpad and one srcpad -* Possible formats on sink and source pad implemented - with custom transform_caps function. By default uses - same format on sink and source. - -* Handles state changes -* Does flushing -* Push mode -* Pull mode if the sub-class transform can operate on arbitrary data - -# Use Cases - -## Passthrough mode - - * Element has no interest in modifying the buffer. It may want to inspect it, - in which case the element should have a transform_ip function. If there - is no transform_ip function in passthrough mode, the buffer is pushed - intact. - - * The #GstBaseTransformClass.passthrough_on_same_caps variable - will automatically set/unset passthrough based on whether the - element negotiates the same caps on both pads. - - * #GstBaseTransformClass.passthrough_on_same_caps on an element that - doesn't implement a transform_caps function is useful for elements that - only inspect data (such as level) - - * Example elements - - * Level - * Videoscale, audioconvert, videoconvert, audioresample in certain modes. - -## Modifications in-place - input buffer and output buffer are the same thing. - -* The element must implement a transform_ip function. -* Output buffer size must <= input buffer size -* If the always_in_place flag is set, non-writable buffers will be copied - and passed to the transform_ip function, otherwise a new buffer will be - created and the transform function called. - -* Incoming writable buffers will be passed to the transform_ip function - immediately. -* only implementing transform_ip and not transform implies always_in_place = %TRUE - - * Example elements: - * Volume - * Audioconvert in certain modes (signed/unsigned conversion) - * videoconvert in certain modes (endianness swapping) - -## Modifications only to the caps/metadata of a buffer - -* The element does not require writable data, but non-writable buffers - should be subbuffered so that the meta-information can be replaced. - -* Elements wishing to operate in this mode should replace the - prepare_output_buffer method to create subbuffers of the input buffer - and set always_in_place to %TRUE - -* Example elements - * Capsfilter when setting caps on outgoing buffers that have - none. - * identity when it is going to re-timestamp buffers by - datarate. - -## Normal mode - * always_in_place flag is not set, or there is no transform_ip function - * Element will receive an input buffer and output buffer to operate on. - * Output buffer is allocated by calling the prepare_output_buffer function. - * Example elements: - * Videoscale, videoconvert, audioconvert when doing - scaling/conversions - -## Special output buffer allocations - * Elements which need to do special allocation of their output buffers - beyond allocating output buffers via the negotiated allocator or - buffer pool should implement the prepare_output_buffer method. - - * Example elements: - * efence - -# Sub-class settable flags on GstBaseTransform - -* passthrough - - * Implies that in the current configuration, the sub-class is not interested in modifying the buffers. - * Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically. - -* always_in_place - * Determines whether a non-writable buffer will be copied before passing - to the transform_ip function. - - * Implied %TRUE if no transform function is implemented. - * Implied %FALSE if ONLY transform function is implemented. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Lets #GstBaseTransform sub-classes know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after use. - - - - - - - a #GstBaseTransform - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - - - the instance of the #GstBufferPool used -by @trans; free it after use - - - - - a #GstBaseTransform - - - - - - See if @trans is configured as a in_place transform. - - - %TRUE if the transform is configured in in_place mode. - -MT safe. - - - - - the #GstBaseTransform to query - - - - - - See if @trans is configured as a passthrough transform. - - - %TRUE if the transform is configured in passthrough mode. - -MT safe. - - - - - the #GstBaseTransform to query - - - - - - Queries if the transform will handle QoS. - - - %TRUE if QoS is enabled. - -MT safe. - - - - - a #GstBaseTransform - - - - - - Negotiates src pad caps with downstream elements if the source pad is -marked as needing reconfiguring. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in -any case. But marks it again if negotiation fails. - -Do not call this in the #GstBaseTransformClass.transform() or -#GstBaseTransformClass.transform_ip() vmethod. Call this in -#GstBaseTransformClass.submit_input_buffer(), -#GstBaseTransformClass.prepare_output_buffer() or in -#GstBaseTransformClass.generate_output() _before_ any output buffer is -allocated. - -It will be default be called when handling an ALLOCATION query or at the -very beginning of the default #GstBaseTransformClass.submit_input_buffer() -implementation. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - the #GstBaseTransform to set - - - - - - Instructs @trans to request renegotiation upstream. This function is -typically called after properties on the transform were set that -influence the input format. - - - - - - - a #GstBaseTransform - - - - - - Instructs @trans to renegotiate a new downstream transform on the next -buffer. This function is typically called after properties on the transform -were set that influence the output format. - - - - - - - a #GstBaseTransform - - - - - - If @gap_aware is %FALSE (the default), output buffers will have the -%GST_BUFFER_FLAG_GAP flag unset. - -If set to %TRUE, the element must handle output buffers with this flag set -correctly, i.e. it can assume that the buffer contains neutral data but must -unset the flag if the output is no neutral data. - -MT safe. - - - - - - - a #GstBaseTransform - - - - New state - - - - - - Determines whether a non-writable buffer will be copied before passing -to the transform_ip function. - - * Always %TRUE if no transform function is implemented. - * Always %FALSE if ONLY transform function is implemented. - -MT safe. - - - - - - - the #GstBaseTransform to modify - - - - Boolean value indicating that we would like to operate -on in_place buffers. - - - - - - Set passthrough mode for this filter by default. This is mostly -useful for filters that do not care about negotiation. - -Always %TRUE for filters which don't implement either a transform -or transform_ip or generate_output method. - -MT safe. - - - - - - - the #GstBaseTransform to set - - - - boolean indicating passthrough mode. - - - - - - If @prefer_passthrough is %TRUE (the default), @trans will check and -prefer passthrough caps from the list of caps returned by the -transform_caps vmethod. - -If set to %FALSE, the element must order the caps returned from the -transform_caps function in such a way that the preferred format is -first in the list. This can be interesting for transforms that can do -passthrough transforms but prefer to do something else, like a -capsfilter. - -MT safe. - - - - - - - a #GstBaseTransform - - - - New state - - - - - - Enable or disable QoS handling in the transform. - -MT safe. - - - - - - - a #GstBaseTransform - - - - new state - - - - - - Set the QoS parameters in the transform. This function is called internally -when a QOS event is received but subclasses can provide custom information -when needed. - -MT safe. - - - - - - - a #GstBaseTransform - - - - the proportion - - - - the diff against the clock - - - - the timestamp of the buffer generating the QoS expressed in -running_time. - - - - - - Updates the srcpad caps and sends the caps downstream. This function -can be used by subclasses when they have already negotiated their caps -but found a change in them (or computed new information). This way, -they can notify downstream about that change without losing any -buffer. - - - %TRUE if the caps could be sent downstream %FALSE otherwise - - - - - a #GstBaseTransform - - - - An updated version of the srcpad caps to be pushed -downstream - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum either @transform or @transform_ip need to be overridden. -If the element can overwrite the input data with the results (data is of the -same type and quantity) it should provide @transform_ip. - - - Element parent class - - - - If set to %TRUE, passthrough mode will be - automatically enabled if the caps are the same. - Set to %FALSE by default. - - - - If set to %TRUE, @transform_ip will be called in - passthrough mode. The passed buffer might not be - writable. When %FALSE, neither @transform nor - @transform_ip will be called in passthrough mode. - Set to %TRUE by default. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstBitReader provides a bit reader that can read any number of bits -from a memory buffer. It provides functions for reading any number of bits -into 8, 16, 32 and 64 bit variables. - - - Data from which the bit reader will - read - - - - - - Size of @data in bytes - - - - Current byte position - - - - Bit position in the current byte - - - - - - - - - Frees a #GstBitReader instance, which was previously allocated by -gst_bit_reader_new(). - - - - - - - a #GstBitReader instance - - - - - - Read @nbits bits into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint16 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint32 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint64 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint8 to store the result - - - - number of bits to read - - - - - - Returns the current position of a #GstBitReader instance in bits. - - - The current position of @reader in bits. - - - - - a #GstBitReader instance - - - - - - Returns the remaining number of bits of a #GstBitReader instance. - - - The remaining number of bits of @reader instance. - - - - - a #GstBitReader instance - - - - - - Returns the total number of bits of a #GstBitReader instance. - - - The total number of bits of @reader instance. - - - - - a #GstBitReader instance - - - - - - Initializes a #GstBitReader instance to read from @data. This function -can be called on already initialized instances. - - - - - - - a #GstBitReader instance - - - - data from which the bit reader should read - - - - - - Size of @data in bytes - - - - - - Read @nbits bits into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint16 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint32 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint64 to store the result - - - - number of bits to read - - - - - - Read @nbits bits into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - Pointer to a #guint8 to store the result - - - - number of bits to read - - - - - - Sets the new position of a #GstBitReader instance to @pos in bits. - - - %TRUE if the position could be set successfully, %FALSE -otherwise. - - - - - a #GstBitReader instance - - - - The new position in bits - - - - - - Skips @nbits bits of the #GstBitReader instance. - - - %TRUE if @nbits bits could be skipped, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - the number of bits to skip - - - - - - Skips until the next byte. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitReader instance - - - - - - Create a new #GstBitReader instance, which will read from @data. - -Free-function: gst_bit_reader_free - - - a new #GstBitReader instance - - - - - Data from which the #GstBitReader - should read - - - - - - Size of @data in bytes - - - - - - - #GstBitWriter provides a bit writer that can write any number of -bits into a memory buffer. It provides functions for writing any -number of bits into 8, 16, 32 and 64 bit variables. - - - Allocated @data for bit writer to write - - - - Size of written @data in bits - - - - - - - - - - - - - - - - - - Write trailing bit to align last byte of @data. @trailing_bit can -only be 1 or 0. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - trailing bits of last byte, 0 or 1 - - - - - - Frees @bitwriter and the allocated data inside. - - - - - - - #GstBitWriter instance - - - - - - Frees @bitwriter without destroying the internal data, which is -returned as #GstBuffer. - -Free-function: gst_buffer_unref - - - a new allocated #GstBuffer wrapping the - data inside. gst_buffer_unref() after usage. - - - - - #GstBitWriter instance - - - - - - Frees @bitwriter without destroying the internal data, which is -returned. - -Free-function: g_free - - - the current data. g_free() after - usage. - - - - - - - #GstBitWriter instance - - - - - - Get written data pointer - - - data pointer - - - - - a #GstBitWriter instance - - - - - - - - - - - - - - - - - Get size of written @data - - - size of bits written in @data - - - - - a #GstBitWriter instance - - - - - - Initializes @bitwriter to an empty instance. - - - - - - - #GstBitWriter instance - - - - - - Initializes @bitwriter with the given memory area @data. IF -@initialized is %TRUE it is possible to read @size bits from the -#GstBitWriter from the beginning. - - - - - - - #GstBitWriter instance - - - - Memory area for writing - - - - - - Size of @data in bytes - - - - If %TRUE the complete data can be read from the beginning - - - - - - Initializes a #GstBitWriter instance and allocates the given data -@size. - - - - - - - #GstBitWriter instance - - - - the size on bytes to allocate for data - - - - If %TRUE the data can't be reallocated - - - - - - Write @nbits bits of @value to #GstBitWriter. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - value of #guint16 to write - - - - number of bits to write - - - - - - Write @nbits bits of @value to #GstBitWriter. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - value of #guint32 to write - - - - number of bits to write - - - - - - Write @nbits bits of @value to #GstBitWriter. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - value of #guint64 to write - - - - number of bits to write - - - - - - Write @nbits bits of @value to #GstBitWriter. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - value of #guint8 to write - - - - number of bits to write - - - - - - Write @nbytes bytes of @data to #GstBitWriter. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstBitWriter instance - - - - pointer of data to write - - - - number of bytes to write - - - - - - Resets @bitwriter and frees the data if it's owned by @bitwriter. - - - - - - - #GstBitWriter instance - - - - - - Resets @bitwriter and returns the current data as #GstBuffer. - -Free-function: gst_buffer_unref - - - a new allocated #GstBuffer wrapping the - current data. gst_buffer_unref() after usage. - - - - - a #GstBitWriter instance - - - - - - Resets @bitwriter and returns the current data. - -Free-function: g_free - - - the current data. g_free() after - usage. - - - - - - - a #GstBitWriter instance - - - - - - - - - - - - - - - - - - - - Creates a new, empty #GstBitWriter instance. - -Free-function: gst_bit_writer_free - - - a new, empty #GstByteWriter instance - - - - - Creates a new #GstBitWriter instance with the given memory area. If -@initialized is %TRUE it is possible to read @size bits from the -#GstBitWriter from the beginning. - -Free-function: gst_bit_writer_free - - - a new #GstBitWriter instance - - - - - Memory area for writing - - - - Size of @data in bytes - - - - if %TRUE the complete data can be read from the beginning - - - - - - Creates a #GstBitWriter instance with the given initial data size. - -Free-function: gst_bit_writer_free - - - a new #GstBitWriter instance - - - - - Initial size of data in bytes - - - - If %TRUE the data can't be reallocated - - - - - - - #GstByteReader provides a byte reader that can read different integer and -floating point types from a memory buffer. It provides functions for reading -signed/unsigned, little/big endian integers of 8, 16, 24, 32 and 64 bits -and functions for reading little/big endian floating points numbers of -32 and 64 bits. It also provides functions to read NUL-terminated strings -in various character encodings. - - - Data from which the bit reader will - read - - - - - - Size of @data in bytes - - - - Current byte position - - - - - - - - - Free-function: g_free - -Returns a newly-allocated copy of the current data -position if at least @size bytes are left and -updates the current position. Free with g_free() when no longer needed. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Size in bytes - - - - address of a - #guint8 pointer variable in which to store the result - - - - - - - - Free-function: g_free - -Returns a newly-allocated copy of the current data position if there is -a NUL-terminated UTF-16 string in the data (this could be an empty string -as well), and advances the current position. - -No input checking for valid UTF-16 is done. This function is endianness -agnostic - you should not assume the UTF-16 characters are in host -endianness. - -This function will fail if no NUL-terminator was found in in the data. - -Note: there is no peek or get variant of this function to ensure correct -byte alignment of the UTF-16 string. - - - %TRUE if a string could be read, %FALSE otherwise. The - string put into @str must be freed with g_free() when no longer needed. - - - - - a #GstByteReader instance - - - - address of a - #guint16 pointer variable in which to store the result - - - - - - - - Free-function: g_free - -Returns a newly-allocated copy of the current data position if there is -a NUL-terminated UTF-32 string in the data (this could be an empty string -as well), and advances the current position. - -No input checking for valid UTF-32 is done. This function is endianness -agnostic - you should not assume the UTF-32 characters are in host -endianness. - -This function will fail if no NUL-terminator was found in in the data. - -Note: there is no peek or get variant of this function to ensure correct -byte alignment of the UTF-32 string. - - - %TRUE if a string could be read, %FALSE otherwise. The - string put into @str must be freed with g_free() when no longer needed. - - - - - a #GstByteReader instance - - - - address of a - #guint32 pointer variable in which to store the result - - - - - - - - Free-function: g_free - -FIXME:Reads (copies) a NUL-terminated string in the #GstByteReader instance, -advancing the current position to the byte after the string. This will work -for any NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be read into @str, %FALSE otherwise. The - string put into @str must be freed with g_free() when no longer needed. - - - - - a #GstByteReader instance - - - - address of a - #gchar pointer variable in which to store the result - - - - - - - - Frees a #GstByteReader instance, which was previously allocated by -gst_byte_reader_new(). - - - - - - - a #GstByteReader instance - - - - - - Returns a constant pointer to the current data -position if at least @size bytes are left and -updates the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Size in bytes - - - - address of a - #guint8 pointer variable in which to store the result - - - - - - - - Read a 32 bit big endian floating point value into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gfloat to store the result - - - - - - Read a 32 bit little endian floating point value into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gfloat to store the result - - - - - - Read a 64 bit big endian floating point value into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gdouble to store the result - - - - - - Read a 64 bit little endian floating point value into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gdouble to store the result - - - - - - Read a signed 16 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint16 to store the result - - - - - - Read a signed 16 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint16 to store the result - - - - - - Read a signed 24 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 24 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 32 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 32 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 64 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint64 to store the result - - - - - - Read a signed 64 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint64 to store the result - - - - - - Read a signed 8 bit integer into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint8 to store the result - - - - - - Returns the current position of a #GstByteReader instance in bytes. - - - The current position of @reader in bytes. - - - - - a #GstByteReader instance - - - - - - Returns the remaining number of bytes of a #GstByteReader instance. - - - The remaining number of bytes of @reader instance. - - - - - a #GstByteReader instance - - - - - - Returns the total number of bytes of a #GstByteReader instance. - - - The total number of bytes of @reader instance. - - - - - a #GstByteReader instance - - - - - - Returns a constant pointer to the current data position if there is -a NUL-terminated string in the data (this could be just a NUL terminator), -advancing the current position to the byte after the string. This will work -for any NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. - -No input checking for valid UTF-8 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be found, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - address of a - #gchar pointer variable in which to store the result - - - - - - - - Initializes a #GstByteReader sub-reader instance to contain @size bytes of -data from the current position of @reader. This is useful to read chunked -formats and make sure that one doesn't read beyond the size of the sub-chunk. - -Unlike gst_byte_reader_peek_sub_reader(), this function also modifies the -position of @reader and moves it forward by @size bytes. - - - FALSE on error or if @reader does not contain @size more bytes from - the current position, and otherwise TRUE - - - - - an existing and initialized #GstByteReader instance - - - - a #GstByteReader instance to initialize as sub-reader - - - - size of @sub_reader in bytes - - - - - - Read an unsigned 16 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint16 to store the result - - - - - - Read an unsigned 16 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint16 to store the result - - - - - - Read an unsigned 24 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 24 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 32 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 32 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 64 bit big endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint64 to store the result - - - - - - Read an unsigned 64 bit little endian integer into @val -and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint64 to store the result - - - - - - Read an unsigned 8 bit integer into @val and update the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint8 to store the result - - - - - - Initializes a #GstByteReader instance to read from @data. This function -can be called on already initialized instances. - - - - - - - a #GstByteReader instance - - - - data from which - the #GstByteReader should read - - - - - - Size of @data in bytes - - - - - - Scan for pattern @pattern with applied mask @mask in the byte reader data, -starting from offset @offset relative to the current position. - -The bytes in @pattern and @mask are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -byte reader data for it to match, even if the first or last bytes are masked -out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the byte reader. - - - offset of the first match, or -1 if no match was found. - -Example: -|[ -// Assume the reader contains 0x00 0x01 0x02 ... 0xfe 0xff - -gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 0, 256); -// -> returns 0 -gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 1, 255); -// -> returns -1 -gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x01020304, 1, 255); -// -> returns 1 -gst_byte_reader_masked_scan_uint32 (reader, 0xffff, 0x0001, 0, 256); -// -> returns -1 -gst_byte_reader_masked_scan_uint32 (reader, 0xffff, 0x0203, 0, 256); -// -> returns 0 -gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 256); -// -> returns 2 -gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 4); -// -> returns -1 -]| - - - - - a #GstByteReader - - - - mask to apply to data before matching against @pattern - - - - pattern to match (after mask is applied) - - - - offset from which to start scanning, relative to the current - position - - - - number of bytes to scan from offset - - - - - - Scan for pattern @pattern with applied mask @mask in the byte reader data, -starting from offset @offset relative to the current position. - -The bytes in @pattern and @mask are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -byte reader data for it to match, even if the first or last bytes are masked -out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the byte reader. - - - offset of the first match, or -1 if no match was found. - - - - - a #GstByteReader - - - - mask to apply to data before matching against @pattern - - - - pattern to match (after mask is applied) - - - - offset from which to start scanning, relative to the current - position - - - - number of bytes to scan from offset - - - - pointer to uint32 to return matching data - - - - - - Returns a constant pointer to the current data -position if at least @size bytes are left and -keeps the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Size in bytes - - - - address of a - #guint8 pointer variable in which to store the result - - - - - - - - Read a 32 bit big endian floating point value into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gfloat to store the result - - - - - - Read a 32 bit little endian floating point value into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gfloat to store the result - - - - - - Read a 64 bit big endian floating point value into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gdouble to store the result - - - - - - Read a 64 bit little endian floating point value into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gdouble to store the result - - - - - - Read a signed 16 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint16 to store the result - - - - - - Read a signed 16 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint16 to store the result - - - - - - Read a signed 24 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 24 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 32 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 32 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint32 to store the result - - - - - - Read a signed 64 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint64 to store the result - - - - - - Read a signed 64 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint64 to store the result - - - - - - Read a signed 8 bit integer into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #gint8 to store the result - - - - - - Returns a constant pointer to the current data position if there is -a NUL-terminated string in the data (this could be just a NUL terminator). -The current position will be maintained. This will work for any -NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. - -No input checking for valid UTF-8 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be skipped, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - address of a - #gchar pointer variable in which to store the result - - - - - - - - Initializes a #GstByteReader sub-reader instance to contain @size bytes of -data from the current position of @reader. This is useful to read chunked -formats and make sure that one doesn't read beyond the size of the sub-chunk. - -Unlike gst_byte_reader_get_sub_reader(), this function does not modify the -current position of @reader. - - - FALSE on error or if @reader does not contain @size more bytes from - the current position, and otherwise TRUE - - - - - an existing and initialized #GstByteReader instance - - - - a #GstByteReader instance to initialize as sub-reader - - - - size of @sub_reader in bytes - - - - - - Read an unsigned 16 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint16 to store the result - - - - - - Read an unsigned 16 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint16 to store the result - - - - - - Read an unsigned 24 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 24 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 32 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 32 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint32 to store the result - - - - - - Read an unsigned 64 bit big endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint64 to store the result - - - - - - Read an unsigned 64 bit little endian integer into @val -but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint64 to store the result - - - - - - Read an unsigned 8 bit integer into @val but keep the current position. - - - %TRUE if successful, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - Pointer to a #guint8 to store the result - - - - - - Sets the new position of a #GstByteReader instance to @pos in bytes. - - - %TRUE if the position could be set successfully, %FALSE -otherwise. - - - - - a #GstByteReader instance - - - - The new position in bytes - - - - - - Skips @nbytes bytes of the #GstByteReader instance. - - - %TRUE if @nbytes bytes could be skipped, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - the number of bytes to skip - - - - - - Skips a NUL-terminated UTF-16 string in the #GstByteReader instance, -advancing the current position to the byte after the string. - -No input checking for valid UTF-16 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be skipped, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - - - Skips a NUL-terminated UTF-32 string in the #GstByteReader instance, -advancing the current position to the byte after the string. - -No input checking for valid UTF-32 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be skipped, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - - - Skips a NUL-terminated string in the #GstByteReader instance, advancing -the current position to the byte after the string. This will work for -any NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. No input checking for valid UTF-8 is done. - -This function will fail if no NUL-terminator was found in in the data. - - - %TRUE if a string could be skipped, %FALSE otherwise. - - - - - a #GstByteReader instance - - - - - - Create a new #GstByteReader instance, which will read from @data. - -Free-function: gst_byte_reader_free - - - a new #GstByteReader instance - - - - - data from which the - #GstByteReader should read - - - - - - Size of @data in bytes - - - - - - - #GstByteWriter provides a byte writer and reader that can write/read different -integer and floating point types to/from a memory buffer. It provides functions -for writing/reading signed/unsigned, little/big endian integers of 8, 16, 24, -32 and 64 bits and functions for reading little/big endian floating points numbers of -32 and 64 bits. It also provides functions to write/read NUL-terminated strings -in various character encodings. - - - #GstByteReader parent - - - - Allocation size of the data - - - - If %TRUE no reallocations are allowed - - - - If %FALSE no reallocations are allowed and copies of data are returned - - - - - - - - - Checks if enough free space from the current write cursor is -available and reallocates if necessary. - - - %TRUE if at least @size bytes are still available - - - - - #GstByteWriter instance - - - - Number of bytes that should be available - - - - - - Writes @size bytes containing @value to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to be written - - - - Number of bytes to be written - - - - - - Frees @writer and all memory allocated by it. - - - - - - - #GstByteWriter instance - - - - - - Frees @writer and all memory allocated by it except -the current data, which is returned as #GstBuffer. - -Free-function: gst_buffer_unref - - - the current data as buffer. gst_buffer_unref() - after usage. - - - - - #GstByteWriter instance - - - - - - Frees @writer and all memory allocated by it except -the current data, which is returned. - -Free-function: g_free - - - the current data. g_free() after usage. - - - - - #GstByteWriter instance - - - - - - Returns the remaining size of data that can still be written. If --1 is returned the remaining size is only limited by system resources. - - - the remaining size of data that can still be written - - - - - #GstByteWriter instance - - - - - - Initializes @writer to an empty instance - - - - - - - #GstByteWriter instance - - - - - - Initializes @writer with the given -memory area. If @initialized is %TRUE it is possible to -read @size bytes from the #GstByteWriter from the beginning. - - - - - - - #GstByteWriter instance - - - - Memory area for writing - - - - - - Size of @data in bytes - - - - If %TRUE the complete data can be read from the beginning - - - - - - Initializes @writer with the given initial data size. - - - - - - - #GstByteWriter instance - - - - Initial size of data - - - - If %TRUE the data can't be reallocated - - - - - - Writes @size bytes of @data to @writer. - - - %TRUE if the data could be written - - - - - #GstByteWriter instance - - - - source #GstBuffer - - - - offset to copy from - - - - total size to copy. If -1, all data is copied - - - - - - Writes @size bytes of @data to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Data to write - - - - - - Size of @data in bytes - - - - - - Writes a big endian 32 bit float to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a little endian 32 bit float to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a big endian 64 bit float to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a little endian 64 bit float to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed big endian 16 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed little endian 16 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed big endian 24 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed little endian 24 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed big endian 32 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed little endian 32 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed big endian 64 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed little endian 64 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a signed 8 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a NUL-terminated UTF16 string to @writer (including the terminator). - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - UTF16 string to write - - - - - - - - Writes a NUL-terminated UTF32 string to @writer (including the terminator). - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - UTF32 string to write - - - - - - - - Writes a NUL-terminated UTF8 string to @writer (including the terminator). - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - UTF8 string to write - - - - - - Writes a unsigned big endian 16 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned little endian 16 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned big endian 24 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned little endian 24 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned big endian 32 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned little endian 32 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned big endian 64 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned little endian 64 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Writes a unsigned 8 bit integer to @writer. - - - %TRUE if the value could be written - - - - - #GstByteWriter instance - - - - Value to write - - - - - - Resets @writer and frees the data if it's -owned by @writer. - - - - - - - #GstByteWriter instance - - - - - - Resets @writer and returns the current data as buffer. - -Free-function: gst_buffer_unref - - - the current data as buffer. gst_buffer_unref() - after usage. - - - - - #GstByteWriter instance - - - - - - Resets @writer and returns the current data. - -Free-function: g_free - - - the current data. g_free() after -usage. - - - - - - - #GstByteWriter instance - - - - - - Creates a new, empty #GstByteWriter instance - -Free-function: gst_byte_writer_free - - - a new, empty #GstByteWriter instance - - - - - Creates a new #GstByteWriter instance with the given -memory area. If @initialized is %TRUE it is possible to -read @size bytes from the #GstByteWriter from the beginning. - -Free-function: gst_byte_writer_free - - - a new #GstByteWriter instance - - - - - Memory area for writing - - - - Size of @data in bytes - - - - If %TRUE the complete data can be read from the beginning - - - - - - Creates a new #GstByteWriter instance with the given -initial data size. - -Free-function: gst_byte_writer_free - - - a new #GstByteWriter instance - - - - - Initial size of data - - - - If %TRUE the data can't be reallocated - - - - - - - - - - - - - - - - - - - - - Returns the DTS that has been converted to running time when using -gst_collect_pads_clip_running_time(). Unlike the value saved into -the buffer, this value is of type gint64 and may be negative. This allow -properly handling streams with frame reordering where the first DTS may -be negative. If the initial DTS was not set, this value will be -set to %G_MININT64. - - - - A #GstCollectData. - - - - - Check if running DTS value store is valid. - - - - A #GstCollectData. - - - - - - - - - - - - Get the stream lock of @pads. The stream lock is used to coordinate and -serialize execution among the various streams being collected, and in -protecting the resources used to accomplish this. - - - - a #GstCollectPads - - - - - A flags word containing #GstCollectPadsStateFlags flags set -on this collected pad. - - - - a #GstCollectData. - - - - - Gives the status of a specific flag on a collected pad. - - - - a #GstCollectData. - - - the #GstCollectPadsStateFlags to check. - - - - - Sets a state flag on a collected pad. - - - - a #GstCollectData. - - - the #GstCollectPadsStateFlags to set. - - - - - Clears a state flag on a collected pad. - - - - a #GstCollectData. - - - the #GstCollectPadsStateFlags to clear. - - - - - Lock the stream lock of @pads. - - - - a #GstCollectPads - - - - - Unlock the stream lock of @pads. - - - - a #GstCollectPads - - - - - Structure used by the collect_pads. - - - owner #GstCollectPads - - - - #GstPad managed by this data - - - - currently queued buffer. - - - - position in the buffer - - - - last segment received. - - - - - - - - - - - - - - - - - - - - - - - - - A function that will be called when the #GstCollectData will be freed. -It is passed the pointer to the structure and should free any custom -memory and resources allocated for it. - - - - - - - the #GstCollectData that will be freed - - - - - - - - - Manages a set of pads that operate in collect mode. This means that control -is given to the manager of this object when all pads have data. - - * Collectpads are created with gst_collect_pads_new(). A callback should then - be installed with gst_collect_pads_set_function (). - - * Pads are added to the collection with gst_collect_pads_add_pad()/ - gst_collect_pads_remove_pad(). The pad has to be a sinkpad. When added, - the chain, event and query functions of the pad are overridden. The - element_private of the pad is used to store private information for the - collectpads. - - * For each pad, data is queued in the _chain function or by - performing a pull_range. - - * When data is queued on all pads in waiting mode, the callback function is called. - - * Data can be dequeued from the pad with the gst_collect_pads_pop() method. - One can peek at the data with the gst_collect_pads_peek() function. - These functions will return %NULL if the pad received an EOS event. When all - pads return %NULL from a gst_collect_pads_peek(), the element can emit an EOS - event itself. - - * Data can also be dequeued in byte units using the gst_collect_pads_available(), - gst_collect_pads_read_buffer() and gst_collect_pads_flush() calls. - - * Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in - their state change functions to start and stop the processing of the collectpads. - The gst_collect_pads_stop() call should be called before calling the parent - element state change function in the PAUSED_TO_READY state change to ensure - no pad is blocked and the element can finish streaming. - - * gst_collect_pads_set_waiting() sets a pad to waiting or non-waiting mode. - CollectPads element is not waiting for data to be collected on non-waiting pads. - Thus these pads may but need not have data when the callback is called. - All pads are in waiting mode by default. - - - Create a new instance of #GstCollectPads. - -MT safe. - - - a new #GstCollectPads, or %NULL in case of an error. - - - - - Add a pad to the collection of collect pads. The pad has to be -a sinkpad. The refcount of the pad is incremented. Use -gst_collect_pads_remove_pad() to remove the pad from the collection -again. - -You specify a size for the returned #GstCollectData structure -so that you can use it to store additional information. - -You can also specify a #GstCollectDataDestroyNotify that will be called -just before the #GstCollectData structure is freed. It is passed the -pointer to the structure and should free any custom memory and resources -allocated for it. - -Keeping a pad locked in waiting state is only relevant when using -the default collection algorithm (providing the oldest buffer). -It ensures a buffer must be available on this pad for a collection -to take place. This is of typical use to a muxer element where -non-subtitle streams should always be in waiting state, -e.g. to assure that caps information is available on all these streams -when initial headers have to be written. - -The pad will be automatically activated in push mode when @pads is -started. - -MT safe. - - - a new #GstCollectData to identify the - new pad. Or %NULL if wrong parameters are supplied. - - - - - the collectpads to use - - - - the pad to add - - - - the size of the returned #GstCollectData structure - - - - function to be called before the returned - #GstCollectData structure is freed - - - - whether to lock this pad in usual waiting state - - - - - - Query how much bytes can be read from each queued buffer. This means -that the result of this call is the maximum number of bytes that can -be read from each of the pads. - -This function should be called with @pads STREAM_LOCK held, such as -in the callback. - -MT safe. - - - The maximum number of bytes queued on all pads. This function -returns 0 if a pad has no queued buffer. - - - - - the collectpads to query - - - - - - Convenience clipping function that converts incoming buffer's timestamp -to running time, or clips the buffer if outside configured segment. - -Since 1.6, this clipping function also sets the DTS parameter of the -GstCollectData structure. This version of the running time DTS can be -negative. G_MININT64 is used to indicate invalid value. - - - - - - - the collectpads to use - - - - collect data of corresponding pad - - - - buffer being clipped - - - - output buffer with running time, or NULL if clipped - - - - user data (unused) - - - - - - Default #GstCollectPads event handling that elements should always -chain up to to ensure proper operation. Element might however indicate -event should not be forwarded downstream. - - - - - - - the collectpads to use - - - - collect data of corresponding pad - - - - event being processed - - - - process but do not send event downstream - - - - - - Flush @size bytes from the pad @data. - -This function should be called with @pads STREAM_LOCK held, such as -in the callback. - -MT safe. - - - The number of bytes flushed This can be less than @size and -is 0 if the pad was end-of-stream. - - - - - the collectpads to query - - - - the data to use - - - - the number of bytes to flush - - - - - - Peek at the buffer currently queued in @data. This function -should be called with the @pads STREAM_LOCK held, such as in the callback -handler. - -MT safe. - - - The buffer in @data or %NULL if no -buffer is queued. should unref the buffer after usage. - - - - - the collectpads to peek - - - - the data to use - - - - - - Pop the buffer currently queued in @data. This function -should be called with the @pads STREAM_LOCK held, such as in the callback -handler. - -MT safe. - - - The buffer in @data or %NULL if no -buffer was queued. You should unref the buffer after usage. - - - - - the collectpads to pop - - - - the data to use - - - - - - Default #GstCollectPads query handling that elements should always -chain up to to ensure proper operation. Element might however indicate -query should not be forwarded downstream. - - - - - - - the collectpads to use - - - - collect data of corresponding pad - - - - query being processed - - - - process but do not send event downstream - - - - - - Get a subbuffer of @size bytes from the given pad @data. - -This function should be called with @pads STREAM_LOCK held, such as in the -callback. - -MT safe. - - - A sub buffer. The size of the buffer can -be less that requested. A return of %NULL signals that the pad is -end-of-stream. Unref the buffer after use. - - - - - the collectpads to query - - - - the data to use - - - - the number of bytes to read - - - - - - Remove a pad from the collection of collect pads. This function will also -free the #GstCollectData and all the resources that were allocated with -gst_collect_pads_add_pad(). - -The pad will be deactivated automatically when @pads is stopped. - -MT safe. - - - %TRUE if the pad could be removed. - - - - - the collectpads to use - - - - the pad to remove - - - - - - Set the callback function and user data that will be called with -the oldest buffer when all pads have been collected, or %NULL on EOS. -If a buffer is passed, the callback owns a reference and must unref -it. - -MT safe. - - - - - - - the collectpads to use - - - - the function to set - - - - user data passed to the function - - - - - - Install a clipping function that is called right after a buffer is received -on a pad managed by @pads. See #GstCollectPadsClipFunction for more info. - - - - - - - the collectpads to use - - - - clip function to install - - - - user data to pass to @clip_func - - - - - - Set the timestamp comparison function. - -MT safe. - - - - - - - the pads to use - - - - the function to set - - - - user data passed to the function - - - - - - Set the event callback function and user data that will be called when -collectpads has received an event originating from one of the collected -pads. If the event being processed is a serialized one, this callback is -called with @pads STREAM_LOCK held, otherwise not. As this lock should be -held when calling a number of CollectPads functions, it should be acquired -if so (unusually) needed. - -MT safe. - - - - - - - the collectpads to use - - - - the function to set - - - - user data passed to the function - - - - - - Install a flush function that is called when the internal -state of all pads should be flushed as part of flushing seek -handling. See #GstCollectPadsFlushFunction for more info. - - - - - - - the collectpads to use - - - - flush function to install - - - - user data to pass to @func - - - - - - Change the flushing state of all the pads in the collection. No pad -is able to accept anymore data when @flushing is %TRUE. Calling this -function with @flushing %FALSE makes @pads accept data again. -Caller must ensure that downstream streaming (thread) is not blocked, -e.g. by sending a FLUSH_START downstream. - -MT safe. - - - - - - - the collectpads to use - - - - desired state of the pads - - - - - - CollectPads provides a default collection algorithm that will determine -the oldest buffer available on all of its pads, and then delegate -to a configured callback. -However, if circumstances are more complicated and/or more control -is desired, this sets a callback that will be invoked instead when -all the pads added to the collection have buffers queued. -Evidently, this callback is not compatible with -gst_collect_pads_set_buffer_function() callback. -If this callback is set, the former will be unset. - -MT safe. - - - - - - - the collectpads to use - - - - the function to set - - - - user data passed to the function - - - - - - Set the query callback function and user data that will be called after -collectpads has received a query originating from one of the collected -pads. If the query being processed is a serialized one, this callback is -called with @pads STREAM_LOCK held, otherwise not. As this lock should be -held when calling a number of CollectPads functions, it should be acquired -if so (unusually) needed. - -MT safe. - - - - - - - the collectpads to use - - - - the function to set - - - - user data passed to the function - - - - - - Sets a pad to waiting or non-waiting mode, if at least this pad -has not been created with locked waiting state, -in which case nothing happens. - -This function should be called with @pads STREAM_LOCK held, such as -in the callback. - -MT safe. - - - - - - - the collectpads - - - - the data to use - - - - boolean indicating whether this pad should operate - in waiting or non-waiting mode - - - - - - Default #GstCollectPads event handling for the src pad of elements. -Elements can chain up to this to let flushing seek event handling -be done by #GstCollectPads. - - - - - - - the #GstCollectPads to use - - - - src #GstPad that received the event - - - - event being processed - - - - - - Starts the processing of data in the collect_pads. - -MT safe. - - - - - - - the collectpads to use - - - - - - Stops the processing of data in the collect_pads. this function -will also unblock any blocking operations. - -MT safe. - - - - - - - the collectpads to use - - - - - - Get a subbuffer of @size bytes from the given pad @data. Flushes the amount -of read bytes. - -This function should be called with @pads STREAM_LOCK held, such as in the -callback. - -MT safe. - - - A sub buffer. The size of the buffer can -be less that requested. A return of %NULL signals that the pad is -end-of-stream. Unref the buffer after use. - - - - - the collectpads to query - - - - the data to use - - - - the number of bytes to read - - - - - - - - - #GList of #GstCollectData managed - by this #GstCollectPads. - - - - - - - - - - - - - - - - - - A function that will be called when a (considered oldest) buffer can be muxed. -If all pads have reached EOS, this function is called with %NULL @buffer -and %NULL @data. - - - %GST_FLOW_OK for success - - - - - the #GstCollectPads that triggered the callback - - - - the #GstCollectData of pad that has received the buffer - - - - the #GstBuffer - - - - user data passed to gst_collect_pads_set_buffer_function() - - - - - - - - - - - - - - - - - A function that will be called when @inbuffer is received on the pad managed -by @data in the collectpad object @pads. - -The function should use the segment of @data and the negotiated media type on -the pad to perform clipping of @inbuffer. - -This function takes ownership of @inbuffer and should output a buffer in -@outbuffer or return %NULL in @outbuffer if the buffer should be dropped. - - - a #GstFlowReturn that corresponds to the result of clipping. - - - - - a #GstCollectPads - - - - a #GstCollectData - - - - the input #GstBuffer - - - - the output #GstBuffer - - - - user data - - - - - - A function for comparing two timestamps of buffers or newsegments collected on one pad. - - - Integer less than zero when first timestamp is deemed older than the second one. - Zero if the timestamps are deemed equally old. - Integer greater than zero when second timestamp is deemed older than the first one. - - - - - the #GstCollectPads that is comparing the timestamps - - - - the first #GstCollectData - - - - the first timestamp - - - - the second #GstCollectData - - - - the second timestamp - - - - user data passed to gst_collect_pads_set_compare_function() - - - - - - A function that will be called while processing an event. It takes -ownership of the event and is responsible for chaining up (to -gst_collect_pads_event_default()) or dropping events (such typical cases -being handled by the default handler). - - - %TRUE if the pad could handle the event - - - - - the #GstCollectPads that triggered the callback - - - - the #GstPad that received an event - - - - the #GstEvent received - - - - user data passed to gst_collect_pads_set_event_function() - - - - - - A function that will be called while processing a flushing seek event. - -The function should flush any internal state of the element and the state of -all the pads. It should clear only the state not directly managed by the -@pads object. It is therefore not necessary to call -gst_collect_pads_set_flushing nor gst_collect_pads_clear from this function. - - - - - - - a #GstCollectPads - - - - user data - - - - - - A function that will be called when all pads have received data. - - - %GST_FLOW_OK for success - - - - - the #GstCollectPads that triggered the callback - - - - user data passed to gst_collect_pads_set_function() - - - - - - - - - A function that will be called while processing a query. It takes -ownership of the query and is responsible for chaining up (to -events downstream (with gst_pad_event_default()). - - - %TRUE if the pad could handle the event - - - - - the #GstCollectPads that triggered the callback - - - - the #GstPad that received an event - - - - the #GstEvent received - - - - user data passed to gst_collect_pads_set_query_function() - - - - - - - - Set if collectdata's pad is EOS. - - - Set if collectdata's pad is flushing. - - - Set if collectdata's pad received a - new_segment event. - - - Set if collectdata's pad must be waited - for when collecting. - - - Set collectdata's pad WAITING state must - not be changed. -#GstCollectPadsStateFlags indicate private state of a collectdata('s pad). - - - - - - - - - - - - - - - - - - #GstDataQueue is an object that handles threadsafe queueing of objects. It -also provides size-related functionality. This object should be used for -any #GstElement that wishes to provide some sort of queueing functionality. - - - Creates a new #GstDataQueue. If @fullcallback or @emptycallback are supplied, then -the #GstDataQueue will call the respective callback to signal full or empty condition. -If the callbacks are NULL the #GstDataQueue will instead emit 'full' and 'empty' -signals. - - - a new #GstDataQueue. - - - - - the callback used to tell if the element considers the queue full -or not. - - - - the callback which will be called when the queue is considered full. - - - - the callback which will be called when the queue is considered empty. - - - - a #gpointer that will be passed to the @checkfull, @fullcallback, - and @emptycallback callbacks. - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pop and unref the head-most #GstMiniObject with the given #GType. - - - %TRUE if an element was removed. - - - - - The #GstDataQueue to drop an item from. - - - - The #GType of the item to drop. - - - - - - Flushes all the contents of the @queue. Any call to #gst_data_queue_push and -#gst_data_queue_pop will be released. -MT safe. - - - - - - - a #GstDataQueue. - - - - - - Get the current level of the queue. - - - - - - - The #GstDataQueue - - - - the location to store the result - - - - - - Queries if there are any items in the @queue. -MT safe. - - - %TRUE if @queue is empty. - - - - - a #GstDataQueue. - - - - - - Queries if @queue is full. This check will be done using the -#GstDataQueueCheckFullFunction registered with @queue. -MT safe. - - - %TRUE if @queue is full. - - - - - a #GstDataQueue. - - - - - - Inform the queue that the limits for the fullness check have changed and that -any blocking gst_data_queue_push() should be unblocked to recheck the limits. - - - - - - - The #GstDataQueue - - - - - - Retrieves the first @item available on the @queue without removing it. -If the queue is currently empty, the call will block until at least -one item is available, OR the @queue is set to the flushing state. -MT safe. - - - %TRUE if an @item was successfully retrieved from the @queue. - - - - - a #GstDataQueue. - - - - pointer to store the returned #GstDataQueueItem. - - - - - - Retrieves the first @item available on the @queue. If the queue is currently -empty, the call will block until at least one item is available, OR the -@queue is set to the flushing state. -MT safe. - - - %TRUE if an @item was successfully retrieved from the @queue. - - - - - a #GstDataQueue. - - - - pointer to store the returned #GstDataQueueItem. - - - - - - Pushes a #GstDataQueueItem (or a structure that begins with the same fields) -on the @queue. If the @queue is full, the call will block until space is -available, OR the @queue is set to flushing state. -MT safe. - -Note that this function has slightly different semantics than gst_pad_push() -and gst_pad_push_event(): this function only takes ownership of @item and -the #GstMiniObject contained in @item if the push was successful. If %FALSE -is returned, the caller is responsible for freeing @item and its contents. - - - %TRUE if the @item was successfully pushed on the @queue. - - - - - a #GstDataQueue. - - - - a #GstDataQueueItem. - - - - - - Pushes a #GstDataQueueItem (or a structure that begins with the same fields) -on the @queue. It ignores if the @queue is full or not and forces the @item -to be pushed anyway. -MT safe. - -Note that this function has slightly different semantics than gst_pad_push() -and gst_pad_push_event(): this function only takes ownership of @item and -the #GstMiniObject contained in @item if the push was successful. If %FALSE -is returned, the caller is responsible for freeing @item and its contents. - - - %TRUE if the @item was successfully pushed on the @queue. - - - - - a #GstDataQueue. - - - - a #GstDataQueueItem. - - - - - - Sets the queue to flushing state if @flushing is %TRUE. If set to flushing -state, any incoming data on the @queue will be discarded. Any call currently -blocking on #gst_data_queue_push or #gst_data_queue_pop will return straight -away with a return value of %FALSE. While the @queue is in flushing state, -all calls to those two functions will return %FALSE. - -MT Safe. - - - - - - - a #GstDataQueue. - - - - a #gboolean stating if the queue will be flushing or not. - - - - - - - - - - - - - - - the parent structure - - - - - - - - - - - - Reports that the queue became empty (empty). -A queue is empty if the total amount of visible items inside it (num-visible, time, -size) is lower than the boundary values which can be set through the GObject -properties. - - - - - - Reports that the queue became full (full). -A queue is full if the total amount of data inside it (num-visible, time, -size) is higher than the boundary values which can be set through the GObject -properties. - - - - - - - The prototype of the function used to inform the queue that it should be -considered as full. - - - %TRUE if the queue should be considered full. - - - - - a #GstDataQueue. - - - - The number of visible items currently in the queue. - - - - The amount of bytes currently in the queue. - - - - The accumulated duration of the items currently in the queue. - - - - The #gpointer registered when the #GstDataQueue was created. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Structure used by #GstDataQueue. You can supply a different structure, as -long as the top of the structure is identical to this structure. - - - the #GstMiniObject to queue. - - - - the size in bytes of the miniobject. - - - - the duration in #GstClockTime of the miniobject. Can not be -%GST_CLOCK_TIME_NONE. - - - - %TRUE if @object should be considered as a visible object. - - - - The #GDestroyNotify function to use to free the #GstDataQueueItem. -This function should also drop the reference to @object the owner of the -#GstDataQueueItem is assumed to hold. - - - - - - - - - - - - - Structure describing the size of a queue. - - - number of buffers - - - - number of bytes - - - - amount of time - - - - - Utility struct to help handling #GstFlowReturn combination. Useful for -#GstElement<!-- -->s that have multiple source pads and need to combine -the different #GstFlowReturn for those pads. - -#GstFlowCombiner works by using the last #GstFlowReturn for all #GstPad -it has in its list and computes the combined return value and provides -it to the caller. - -To add a new pad to the #GstFlowCombiner use gst_flow_combiner_add_pad(). -The new #GstPad is stored with a default value of %GST_FLOW_OK. - -In case you want a #GstPad to be removed, use gst_flow_combiner_remove_pad(). - -Please be aware that this struct isn't thread safe as its designed to be - used by demuxers, those usually will have a single thread operating it. - -These functions will take refs on the passed #GstPad<!-- -->s. - -Aside from reducing the user's code size, the main advantage of using this -helper struct is to follow the standard rules for #GstFlowReturn combination. -These rules are: - -* %GST_FLOW_EOS: only if all returns are EOS too -* %GST_FLOW_NOT_LINKED: only if all returns are NOT_LINKED too -* %GST_FLOW_ERROR or below: if at least one returns an error return -* %GST_FLOW_NOT_NEGOTIATED: if at least one returns a not-negotiated return -* %GST_FLOW_FLUSHING: if at least one returns flushing -* %GST_FLOW_OK: otherwise - -%GST_FLOW_ERROR or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are -returned immediately from the gst_flow_combiner_update_flow() function. - - - Creates a new #GstFlowCombiner, use gst_flow_combiner_free() to free it. - - - A new #GstFlowCombiner - - - - - Adds a new #GstPad to the #GstFlowCombiner. - - - - - - - the #GstFlowCombiner - - - - the #GstPad that is being added - - - - - - Removes all pads from a #GstFlowCombiner and resets it to its initial state. - - - - - - - the #GstFlowCombiner to clear - - - - - - Frees a #GstFlowCombiner struct and all its internal data. - - - - - - - the #GstFlowCombiner to free - - - - - - Increments the reference count on the #GstFlowCombiner. - - - the #GstFlowCombiner. - - - - - the #GstFlowCombiner to add a reference to. - - - - - - Removes a #GstPad from the #GstFlowCombiner. - - - - - - - the #GstFlowCombiner - - - - the #GstPad to remove - - - - - - Reset flow combiner and all pads to their initial state without removing pads. - - - - - - - the #GstFlowCombiner to clear - - - - - - Decrements the reference count on the #GstFlowCombiner. - - - - - - - the #GstFlowCombiner to unreference. - - - - - - Computes the combined flow return for the pads in it. - -The #GstFlowReturn parameter should be the last flow return update for a pad -in this #GstFlowCombiner. It will use this value to be able to shortcut some -combinations and avoid looking over all pads again. e.g. The last combined -return is the same as the latest obtained #GstFlowReturn. - - - The combined #GstFlowReturn - - - - - the #GstFlowCombiner - - - - the latest #GstFlowReturn received for a pad in this #GstFlowCombiner - - - - - - Sets the provided pad's last flow return to provided value and computes -the combined flow return for the pads in it. - -The #GstFlowReturn parameter should be the last flow return update for a pad -in this #GstFlowCombiner. It will use this value to be able to shortcut some -combinations and avoid looking over all pads again. e.g. The last combined -return is the same as the latest obtained #GstFlowReturn. - - - The combined #GstFlowReturn - - - - - the #GstFlowCombiner - - - - the #GstPad whose #GstFlowReturn to update - - - - the latest #GstFlowReturn received for a pad in this #GstFlowCombiner - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This class is mostly useful for elements that cannot do -random access, or at least very slowly. The source usually -prefers to push out a fixed size buffer. - -Subclasses usually operate in a format that is different from the -default GST_FORMAT_BYTES format of #GstBaseSrc. - -Classes extending this base class will usually be scheduled -in a push based mode. If the peer accepts to operate without -offsets and within the limits of the allowed block size, this -class can operate in getrange based mode automatically. To make -this possible, the subclass should implement and override the -SCHEDULING query. - -The subclass should extend the methods from the baseclass in -addition to the ::create method. - -Seeking, flushing, scheduling and sync is all handled by this -base class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At the minimum, the @fill method should be overridden to produce -buffers. - - - Element parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstQueueArray is an object that provides standard queue functionality -based on an array instead of linked lists. This reduces the overhead -caused by memory management by a large factor. - - - Clears queue @array and frees all memory associated to it. - - - - - - - a #GstQueueArray object - - - - - - Drops the queue element at position @idx from queue @array. - - - the dropped element - - - - - a #GstQueueArray object - - - - index to drop - - - - - - Drops the queue element at position @idx from queue @array and copies the -data of the element or structure that was removed into @p_struct if -@p_struct is set (not NULL). - - - TRUE on success, or FALSE on error - - - - - a #GstQueueArray object - - - - index to drop - - - - address into which to store the data of the dropped structure, or NULL - - - - - - Finds an element in the queue @array, either by comparing every element -with @func or by looking up @data if no compare function @func is provided, -and returning the index of the found element. - - - Index of the found element or -1 if nothing was found. - - - - - a #GstQueueArray object - - - - comparison function, or %NULL to find @data by value - - - - data for comparison function - - - - - - Frees queue @array and all memory associated to it. - - - - - - - a #GstQueueArray object - - - - - - Returns the length of the queue @array - - - the length of the queue @array. - - - - - a #GstQueueArray object - - - - - - Checks if the queue @array is empty. - - - %TRUE if the queue @array is empty - - - - - a #GstQueueArray object - - - - - - Returns the head of the queue @array and does not -remove it from the queue. - - - The head of the queue - - - - - a #GstQueueArray object - - - - - - Returns the head of the queue @array without removing it from the queue. - - - pointer to element or struct, or NULL if @array was empty. The - data pointed to by the returned pointer stays valid only as long as - the queue array is not modified further! - - - - - a #GstQueueArray object - - - - - - Returns the item at @idx in @array, but does not remove it from the queue. - - - The item, or %NULL if @idx was out of bounds - - - - - - - - - - - - - Returns the item at @idx in @array, but does not remove it from the queue. - - - The item, or %NULL if @idx was out of bounds - - - - - - - - - - - - - Returns the tail of the queue @array, but does not remove it from the queue. - - - The tail of the queue - - - - - a #GstQueueArray object - - - - - - Returns the tail of the queue @array, but does not remove it from the queue. - - - The tail of the queue - - - - - a #GstQueueArray object - - - - - - Returns and head of the queue @array and removes -it from the queue. - - - The head of the queue - - - - - a #GstQueueArray object - - - - - - Returns the head of the queue @array and removes it from the queue. - - - pointer to element or struct, or NULL if @array was empty. The - data pointed to by the returned pointer stays valid only as long as - the queue array is not modified further! - - - - - a #GstQueueArray object - - - - - - Returns the tail of the queue @array and removes -it from the queue. - - - The tail of the queue - - - - - a #GstQueueArray object - - - - - - Returns the tail of the queue @array and removes -it from the queue. - - - The tail of the queue - - - - - a #GstQueueArray object - - - - - - Pushes @data to the tail of the queue @array. - - - - - - - a #GstQueueArray object - - - - object to push - - - - - - - - - - - - - - - - - - - - Sets a function to clear an element of @array. - -The @clear_func will be called when an element in the array -data segment is removed and when the array is freed and data -segment is deallocated as well. @clear_func will be passed a -pointer to the element to clear, rather than the element itself. - -Note that in contrast with other uses of #GDestroyNotify -functions, @clear_func is expected to clear the contents of -the array element it is given, but not free the element itself. - - - - - - - a #GstQueueArray object - - - - a function to clear an element of @array - - - - - - Allocates a new #GstQueueArray object with an initial -queue size of @initial_size. - - - a new #GstQueueArray object - - - - - Initial size of the new queue - - - - - - Allocates a new #GstQueueArray object for elements (e.g. structures) -of size @struct_size, with an initial queue size of @initial_size. - - - a new #GstQueueArray object - - - - - Size of each element (e.g. structure) in the array - - - - Initial size of the new queue - - - - - - - This function will be called by gst_type_find_helper_get_range() when -typefinding functions request to peek at the data of a stream at certain -offsets. If this function returns GST_FLOW_OK, the result buffer will be -stored in @buffer. The contents of @buffer is invalid for any other -return value. - -This function is supposed to behave exactly like a #GstPadGetRangeFunction. - - - GST_FLOW_OK for success - - - - - a #GstObject that will handle the getrange request - - - - the parent of @obj or %NULL - - - - the offset of the range - - - - the length of the range - - - - a memory location to hold the result buffer - - - - - - Create a new #GstBitReader instance, which will read from @data. - -Free-function: gst_bit_reader_free - - - a new #GstBitReader instance - - - - - Data from which the #GstBitReader - should read - - - - - - Size of @data in bytes - - - - - - Creates a new, empty #GstBitWriter instance. - -Free-function: gst_bit_writer_free - - - a new, empty #GstByteWriter instance - - - - - Creates a new #GstBitWriter instance with the given memory area. If -@initialized is %TRUE it is possible to read @size bits from the -#GstBitWriter from the beginning. - -Free-function: gst_bit_writer_free - - - a new #GstBitWriter instance - - - - - Memory area for writing - - - - Size of @data in bytes - - - - if %TRUE the complete data can be read from the beginning - - - - - - Creates a #GstBitWriter instance with the given initial data size. - -Free-function: gst_bit_writer_free - - - a new #GstBitWriter instance - - - - - Initial size of data in bytes - - - - If %TRUE the data can't be reallocated - - - - - - - - - - - - - - - - - - - - - - - - Create a new #GstByteReader instance, which will read from @data. - -Free-function: gst_byte_reader_free - - - a new #GstByteReader instance - - - - - data from which the - #GstByteReader should read - - - - - - Size of @data in bytes - - - - - - Returns a constant pointer to the current data position if there is -a NUL-terminated string in the data (this could be just a NUL terminator). -The current position will be maintained. This will work for any -NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. - -This function will fail if no NUL-terminator was found in in the data. - - - - a #GstByteReader instance - - - address of a - #gchar pointer variable in which to store the result - - - - - Skips a NUL-terminated string in the #GstByteReader instance, advancing -the current position to the byte after the string. This will work for -any NUL-terminated string with a character width of 8 bits, so ASCII, -UTF-8, ISO-8859-N etc. - -This function will fail if no NUL-terminator was found in in the data. - - - - a #GstByteReader instance - - - - - Creates a new, empty #GstByteWriter instance - -Free-function: gst_byte_writer_free - - - a new, empty #GstByteWriter instance - - - - - Creates a new #GstByteWriter instance with the given -memory area. If @initialized is %TRUE it is possible to -read @size bytes from the #GstByteWriter from the beginning. - -Free-function: gst_byte_writer_free - - - a new #GstByteWriter instance - - - - - Memory area for writing - - - - Size of @data in bytes - - - - If %TRUE the complete data can be read from the beginning - - - - - - Creates a new #GstByteWriter instance with the given -initial data size. - -Free-function: gst_byte_writer_free - - - a new #GstByteWriter instance - - - - - Initial size of data - - - - If %TRUE the data can't be reallocated - - - - - - Write a NUL-terminated string to @writer (including the terminator). The -string is assumed to be in an 8-bit encoding (e.g. ASCII,UTF-8 or -ISO-8859-1). - - - - #GstByteWriter instance - - - Null terminated string - - - - - Allocates a new #GstQueueArray object with an initial -queue size of @initial_size. - - - a new #GstQueueArray object - - - - - Initial size of the new queue - - - - - - Allocates a new #GstQueueArray object for elements (e.g. structures) -of size @struct_size, with an initial queue size of @initial_size. - - - a new #GstQueueArray object - - - - - Size of each element (e.g. structure) in the array - - - - Initial size of the new queue - - - - - - Tries to find what type of data is flowing from the given source #GstPad. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data - stream. Returns %NULL if no #GstCaps matches the data stream. - - - - - A source #GstPad - - - - The length in bytes - - - - - - Tries to find what type of data is contained in the given #GstBuffer, the -assumption being that the buffer represents the beginning of the stream or -file. - -All available typefinders will be called on the data in order of rank. If -a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM, -typefinding is stopped immediately and the found caps will be returned -right away. Otherwise, all available typefind functions will the tried, -and the caps with the highest probability will be returned, or %NULL if -the content of the buffer could not be identified. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data, - or %NULL if no type could be found. The caller should free the caps - returned with gst_caps_unref(). - - - - - object doing the typefinding, or %NULL (used for logging) - - - - a #GstBuffer with data to typefind - - - - location to store the probability of the found - caps, or %NULL - - - - - - Tries to find what type of data is contained in the given #GstBuffer, the -assumption being that the buffer represents the beginning of the stream or -file. - -All available typefinders will be called on the data in order of rank. If -a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM, -typefinding is stopped immediately and the found caps will be returned -right away. Otherwise, all available typefind functions will the tried, -and the caps with the highest probability will be returned, or %NULL if -the content of the buffer could not be identified. - -When @extension is not %NULL, this function will first try the typefind -functions for the given extension, which might speed up the typefinding -in many cases. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data, - or %NULL if no type could be found. The caller should free the caps - returned with gst_caps_unref(). - - - - - object doing the typefinding, or %NULL (used for logging) - - - - a #GstBuffer with data to typefind - - - - extension of the media, or %NULL - - - - location to store the probability of the found - caps, or %NULL - - - - - - Tries to find what type of data is contained in the given @data, the -assumption being that the data represents the beginning of the stream or -file. - -All available typefinders will be called on the data in order of rank. If -a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM, -typefinding is stopped immediately and the found caps will be returned -right away. Otherwise, all available typefind functions will the tried, -and the caps with the highest probability will be returned, or %NULL if -the content of @data could not be identified. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data, - or %NULL if no type could be found. The caller should free the caps - returned with gst_caps_unref(). - - - - - object doing the typefinding, or %NULL (used for logging) - - - - * a pointer with data to typefind - - - - - - the size of @data - - - - location to store the probability of the found - caps, or %NULL - - - - - - Tries to find what type of data is contained in the given @data, the -assumption being that the data represents the beginning of the stream or -file. - -All available typefinders will be called on the data in order of rank. If -a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM, -typefinding is stopped immediately and the found caps will be returned -right away. Otherwise, all available typefind functions will the tried, -and the caps with the highest probability will be returned, or %NULL if -the content of @data could not be identified. - -When @extension is not %NULL, this function will first try the typefind -functions for the given extension, which might speed up the typefinding -in many cases. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data, - or %NULL if no type could be found. The caller should free the caps - returned with gst_caps_unref(). - - - - - object doing the typefinding, or %NULL (used for logging) - - - - * a pointer with data to typefind - - - - - - the size of @data - - - - extension of the media, or %NULL - - - - location to store the probability of the found - caps, or %NULL - - - - - - Tries to find the best #GstCaps associated with @extension. - -All available typefinders will be checked against the extension in order -of rank. The caps of the first typefinder that can handle @extension will be -returned. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to - @extension, or %NULL if no type could be found. The caller should free - the caps returned with gst_caps_unref(). - - - - - object doing the typefinding, or %NULL (used for logging) - - - - an extension - - - - - - Utility function to do pull-based typefinding. Unlike gst_type_find_helper() -however, this function will use the specified function @func to obtain the -data needed by the typefind functions, rather than operating on a given -source pad. This is useful mostly for elements like tag demuxers which -strip off data at the beginning and/or end of a file and want to typefind -the stripped data stream before adding their own source pad (the specified -callback can then call the upstream peer pad with offsets adjusted for the -tag size, for example). - -When @extension is not %NULL, this function will first try the typefind -functions for the given extension, which might speed up the typefinding -in many cases. - -Free-function: gst_caps_unref - - - the #GstCaps corresponding to the data - stream. Returns %NULL if no #GstCaps matches the data stream. - - - - - A #GstObject that will be passed as first argument to @func - - - - the parent of @obj or %NULL - - - - A generic #GstTypeFindHelperGetRangeFunction that will - be used to access data at random offsets when doing the typefinding - - - - The length in bytes - - - - extension of the media, or %NULL - - - - location to store the probability of the found - caps, or %NULL - - - - - - Utility function to do pull-based typefinding. Unlike gst_type_find_helper() -however, this function will use the specified function @func to obtain the -data needed by the typefind functions, rather than operating on a given -source pad. This is useful mostly for elements like tag demuxers which -strip off data at the beginning and/or end of a file and want to typefind -the stripped data stream before adding their own source pad (the specified -callback can then call the upstream peer pad with offsets adjusted for the -tag size, for example). - -When @extension is not %NULL, this function will first try the typefind -functions for the given extension, which might speed up the typefinding -in many cases. - - - the last %GstFlowReturn from pulling a buffer or %GST_FLOW_OK if - typefinding was successful. - - - - - A #GstObject that will be passed as first argument to @func - - - - the parent of @obj or %NULL - - - - A generic #GstTypeFindHelperGetRangeFunction that will - be used to access data at random offsets when doing the typefinding - - - - The length in bytes - - - - extension of the media, or %NULL - - - - returned caps - - - - location to store the probability of the found - caps, or %NULL - - - - - - diff --git a/gir-files/GstCheck-1.0.gir b/gir-files/GstCheck-1.0.gir deleted file mode 100644 index ac92a8f67..000000000 --- a/gir-files/GstCheck-1.0.gir +++ /dev/null @@ -1,3038 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - #GstHarness is meant to make writing unit test for GStreamer much easier. -It can be thought of as a way of treating a #GstElement as a black box, -deterministically feeding it data, and controlling what data it outputs. - -The basic structure of #GstHarness is two "floating" #GstPads that connect -to the harnessed #GstElement src and sink #GstPads like so: - -|[ - __________________________ - _____ | _____ _____ | _____ -| | | | | | | | | | -| src |--+-| sink| Element | src |-+--| sink| -|_____| | |_____| |_____| | |_____| - |__________________________| - -]| - -With this, you can now simulate any environment the #GstElement might find -itself in. By specifying the #GstCaps of the harness #GstPads, using -functions like gst_harness_set_src_caps() or gst_harness_set_sink_caps_str(), -you can test how the #GstElement interacts with different caps sets. - -Your harnessed #GstElement can of course also be a bin, and using -gst_harness_new_parse() supporting standard gst-launch syntax, you can -easily test a whole pipeline instead of just one element. - -You can then go on to push #GstBuffers and #GstEvents on to the srcpad, -using functions like gst_harness_push() and gst_harness_push_event(), and -then pull them out to examine them with gst_harness_pull() and -gst_harness_pull_event(). - -## A simple buffer-in buffer-out example - -|[<!-- language="C" --> - #include <gst/gst.h> - #include <gst/check/gstharness.h> - GstHarness *h; - GstBuffer *in_buf; - GstBuffer *out_buf; - - // attach the harness to the src and sink pad of GstQueue - h = gst_harness_new ("queue"); - - // we must specify a caps before pushing buffers - gst_harness_set_src_caps_str (h, "mycaps"); - - // create a buffer of size 42 - in_buf = gst_harness_create_buffer (h, 42); - - // push the buffer into the queue - gst_harness_push (h, in_buf); - - // pull the buffer from the queue - out_buf = gst_harness_pull (h); - - // validate the buffer in is the same as buffer out - fail_unless (in_buf == out_buf); - - // cleanup - gst_buffer_unref (out_buf); - gst_harness_teardown (h); - - ]| - -Another main feature of the #GstHarness is its integration with the -#GstTestClock. Operating the #GstTestClock can be very challenging, but -#GstHarness simplifies some of the most desired actions a lot, like wanting -to manually advance the clock while at the same time releasing a #GstClockID -that is waiting, with functions like gst_harness_crank_single_clock_wait(). - -#GstHarness also supports sub-harnesses, as a way of generating and -validating data. A sub-harness is another #GstHarness that is managed by -the "parent" harness, and can either be created by using the standard -gst_harness_new type functions directly on the (GstHarness *)->src_harness, -or using the much more convenient gst_harness_add_src() or -gst_harness_add_sink_parse(). If you have a decoder-element you want to test, -(like vp8dec) it can be very useful to add a src-harness with both a -src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data -with different configurations, by simply doing: - -|[<!-- language="C" --> - GstHarness * h = gst_harness_new (h, "vp8dec"); - gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE); -]| - -and then feeding it data with: - -|[<!-- language="C" --> -gst_harness_push_from_src (h); -]| - - - the element inside the harness - - - - the internal harness source pad - - - - the internal harness sink pad - - - - the source (input) harness (if any) - - - - the sink (output) harness (if any) - - - - - - - Adds a #GstElement to an empty #GstHarness - -MT safe. - - - - - - - a #GstHarness - - - - a #GstElement to add to the harness (transfer none) - - - - a #GstStaticPadTemplate describing the harness srcpad. -%NULL will not create a harness srcpad. - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. Can be a static or request -or a sometimes pad that has been added. %NULL will not get/request a sinkpad -from the element. (Like if the element is a src.) - - - - a #GstStaticPadTemplate describing the harness sinkpad. -%NULL will not create a harness sinkpad. - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad, similar to the -@element_sinkpad_name. - - - - - - Links the specified #GstPad the @GstHarness srcpad. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstPad to link to the harness srcpad - - - - - - Links the specified #GstPad the @GstHarness sinkpad. This can be useful if -perhaps the srcpad did not exist at the time of creating the harness, -like a demuxer that provides a sometimes-pad after receiving data. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstPad to link to the harness sinkpad - - - - - - Parses the @launchline and puts that in a #GstBin, -and then attches the supplied #GstHarness to the bin. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar describing a gst-launch type line - - - - - - A convenience function to allows you to call gst_pad_add_probe on a -#GstPad of a #GstElement that are residing inside the #GstHarness, -by using normal gst_pad_add_probe syntax - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with a #GstElementFactory name - - - - a #gchar with the name of the pad to attach the probe to - - - - a #GstPadProbeType (see gst_pad_add_probe) - - - - a #GstPadProbeCallback (see gst_pad_add_probe) - - - - a #gpointer (see gst_pad_add_probe) - - - - a #GDestroyNotify (see gst_pad_add_probe) - - - - - - Add api with params as one of the supported metadata API to propose when -receiving an allocation query. - -MT safe. - - - - - - - a #GstHarness - - - - a metadata API - - - - API specific parameters - - - - - - Similar to gst_harness_add_sink_harness, this is a convenience to -directly create a sink-harness using the @sink_element_name name specified. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with the name of a #GstElement - - - - - - Similar to gst_harness_add_src, this allows you to send the data coming out -of your harnessed #GstElement to a sink-element, allowing to test different -responses the element output might create in sink elements. An example might -be an existing sink providing some analytical data on the input it receives that -can be useful to your testing. If the goal is to test a sink-element itself, -this is better achieved using gst_harness_new directly on the sink. - -If a sink-harness already exists it will be replaced. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstHarness to be added as a sink-harness. - - - - - - Similar to gst_harness_add_sink, this allows you to specify a launch-line -instead of just an element name. See gst_harness_add_src_parse for details. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with the name of a #GstElement - - - - - - Similar to gst_harness_add_src_harness, this is a convenience to -directly create a src-harness using the @src_element_name name specified. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with the name of a #GstElement - - - - a #gboolean specifying if the #GstElement uses -gst_clock_wait_id internally. - - - - - - A src-harness is a great way of providing the #GstHarness with data. -By adding a src-type #GstElement, it is then easy to use functions like -gst_harness_push_from_src or gst_harness_src_crank_and_push_many -to provide your harnessed element with input. The @has_clock_wait variable -is a great way to control you src-element with, in that you can have it -produce a buffer for you by simply cranking the clock, and not have it -spin out of control producing buffers as fast as possible. - -If a src-harness already exists it will be replaced. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstHarness to be added as a src-harness. - - - - a #gboolean specifying if the #GstElement uses -gst_clock_wait_id internally. - - - - - - Similar to gst_harness_add_src, this allows you to specify a launch-line, -which can be useful for both having more then one #GstElement acting as your -src (Like a src producing raw buffers, and then an encoder, providing encoded -data), but also by allowing you to set properties like "is-live" directly on -the elements. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar describing a gst-launch type line - - - - a #gboolean specifying if the #GstElement uses -gst_clock_wait_id internally. - - - - - - The number of #GstBuffers currently in the #GstHarness sinkpad #GAsyncQueue - -MT safe. - - - a #guint number of buffers in the queue - - - - - a #GstHarness - - - - - - The total number of #GstBuffers that has arrived on the #GstHarness sinkpad. -This number includes buffers that have been dropped as well as buffers -that have already been pulled out. - -MT safe. - - - a #guint number of buffers received - - - - - a #GstHarness - - - - - - Similar to gst_harness_crank_single_clock_wait(), this is the function to use -if your harnessed element(s) are using more then one gst_clock_id_wait. -Failing to do so can (and will) make it racy which #GstClockID you actually -are releasing, where as this function will process all the waits at the -same time, ensuring that one thread can't register another wait before -both are released. - -MT safe. - - - a @gboolean %TRUE if the "crank" was successful, %FALSE if not. - - - - - a #GstHarness - - - - a #guint describing the number of #GstClockIDs to crank - - - - - - A "crank" consists of three steps: -1: Wait for a #GstClockID to be registered with the #GstTestClock. -2: Advance the #GstTestClock to the time the #GstClockID is waiting for. -3: Release the #GstClockID wait. -Together, this provides an easy way to not have to think about the details -around clocks and time, but still being able to write deterministic tests -that are dependent on this. A "crank" can be though of as the notion of -manually driving the clock forward to its next logical step. - -MT safe. - - - a @gboolean %TRUE if the "crank" was successful, %FALSE if not. - - - - - a #GstHarness - - - - - - Allocates a buffer using a #GstBufferPool if present, or else using the -configured #GstAllocator and #GstAllocationParams - -MT safe. - - - a #GstBuffer of size @size - - - - - a #GstHarness - - - - a #gsize specifying the size of the buffer - - - - - - Allows you to dump the #GstBuffers the #GstHarness sinkpad #GAsyncQueue -to a file. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with a the name of a file - - - - - - The number of #GstEvents currently in the #GstHarness sinkpad #GAsyncQueue - -MT safe. - - - a #guint number of events in the queue - - - - - a #GstHarness - - - - - - The total number of #GstEvents that has arrived on the #GstHarness sinkpad -This number includes events handled by the harness as well as events -that have already been pulled out. - -MT safe. - - - a #guint number of events received - - - - - a #GstHarness - - - - - - Most useful in conjunction with gst_harness_new_parse, this will scan the -#GstElements inside the #GstHarness, and check if any of them matches -@element_name. Typical usecase being that you need to access one of the -harnessed elements for properties and/or signals. - -MT safe. - - - a #GstElement or %NULL if not found - - - - - a #GstHarness - - - - a #gchar with a #GstElementFactory name - - - - - - A convenience function to allows you to call g_object_get on a #GstElement -that are residing inside the #GstHarness, by using normal g_object_get -syntax. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with a #GstElementFactory name - - - - a #gchar with the first property name - - - - return location for the first property, followed optionally by more - name/return location pairs, followed by %NULL - - - - - - Gets the @allocator and its @params that has been decided to use after an -allocation query. - -MT safe. - - - - - - - a #GstHarness - - - - the #GstAllocator used - - - - the #GstAllocationParams of - @allocator - - - - - - Get the timestamp of the last #GstBuffer pushed on the #GstHarness srcpad, -typically with gst_harness_push or gst_harness_push_from_src. - -MT safe. - - - a #GstClockTime with the timestamp or %GST_CLOCK_TIME_NONE if no -#GstBuffer has been pushed on the #GstHarness srcpad - - - - - a #GstHarness - - - - - - Get the #GstTestClock. Useful if specific operations on the testclock is -needed. - -MT safe. - - - a #GstTestClock, or %NULL if the testclock is not -present. - - - - - a #GstHarness - - - - - - This will set the harnessed #GstElement to %GST_STATE_PLAYING. -#GstElements without a sink-#GstPad and with the %GST_ELEMENT_FLAG_SOURCE -flag set is considered a src #GstElement -Non-src #GstElements (like sinks and filters) are automatically set to -playing by the #GstHarness, but src #GstElements are not to avoid them -starting to produce buffers. -Hence, for src #GstElement you must call gst_harness_play() explicitly. - -MT safe. - - - - - - - a #GstHarness - - - - - - Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. The pull -will timeout in 60 seconds. This is the standard way of getting a buffer -from a harnessed #GstElement. - -MT safe. - - - a #GstBuffer or %NULL if timed out. - - - - - a #GstHarness - - - - - - Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. -Timeouts after 60 seconds similar to gst_harness_pull. - -MT safe. - - - a #GstEvent or %NULL if timed out. - - - - - a #GstHarness - - - - - - Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. The pull -will block until an EOS event is received, or timeout in 60 seconds. -MT safe. - - - %TRUE on success, %FALSE on timeout. - - - - - a #GstHarness - - - - A #GstBuffer, or %NULL if EOS or timeout occures - first. - - - - - - Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. -Timeouts after 60 seconds similar to gst_harness_pull. - -MT safe. - - - a #GstEvent or %NULL if timed out. - - - - - a #GstHarness - - - - - - Pushes a #GstBuffer on the #GstHarness srcpad. The standard way of -interacting with an harnessed element. - -MT safe. - - - a #GstFlowReturn with the result from the push - - - - - a #GstHarness - - - - a #GstBuffer to push - - - - - - Basically a gst_harness_push and a gst_harness_pull in one line. Reflects -the fact that you often want to do exactly this in your test: Push one buffer -in, and inspect the outcome. - -MT safe. - - - a #GstBuffer or %NULL if timed out. - - - - - a #GstHarness - - - - a #GstBuffer to push - - - - - - Pushes an #GstEvent on the #GstHarness srcpad. - -MT safe. - - - a #gboolean with the result from the push - - - - - a #GstHarness - - - - a #GstEvent to push - - - - - - Transfer data from the src-#GstHarness to the main-#GstHarness. It consists -of 4 steps: -1: Make sure the src is started. (see: gst_harness_play) -2: Crank the clock (see: gst_harness_crank_single_clock_wait) -3: Pull a #GstBuffer from the src-#GstHarness (see: gst_harness_pull) -4: Push the same #GstBuffer into the main-#GstHarness (see: gst_harness_push) - -MT safe. - - - a #GstFlowReturn with the result of the push - - - - - a #GstHarness - - - - - - Transfer one #GstBuffer from the main-#GstHarness to the sink-#GstHarness. -See gst_harness_push_from_src for details. - -MT safe. - - - a #GstFlowReturn with the result of the push - - - - - a #GstHarness - - - - - - Pushes an #GstEvent on the #GstHarness sinkpad. - -MT safe. - - - a #gboolean with the result from the push - - - - - a #GstHarness - - - - a #GstEvent to push - - - - - - Get the min latency reported by any harnessed #GstElement. - -MT safe. - - - a #GstClockTime with min latency - - - - - a #GstHarness - - - - - - A convenience function to allows you to call g_object_set on a #GstElement -that are residing inside the #GstHarness, by using normal g_object_set -syntax. - -MT safe. - - - - - - - a #GstHarness - - - - a #gchar with a #GstElementFactory name - - - - a #gchar with the first property name - - - - value for the first property, followed optionally by more - name/value pairs, followed by %NULL - - - - - - Setting this will make the harness block in the chain-function, and -then release when gst_harness_pull() or gst_harness_try_pull() is called. -Can be useful when wanting to control a src-element that is not implementing -gst_clock_id_wait() so it can't be controlled by the #GstTestClock, since -it otherwise would produce buffers as fast as possible. - -MT safe. - - - - - - - a #GstHarness - - - - - - Sets the @GstHarness srcpad and sinkpad caps. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstCaps to set on the harness srcpad - - - - a #GstCaps to set on the harness sinkpad - - - - - - Sets the @GstHarness srcpad and sinkpad caps using strings. - -MT safe. - - - - - - - a #GstHarness - - - - a @gchar describing a #GstCaps to set on the harness srcpad - - - - a @gchar describing a #GstCaps to set on the harness sinkpad - - - - - - When set to %TRUE, instead of placing the buffers arriving from the harnessed -#GstElement inside the sinkpads #GAsyncQueue, they are instead unreffed. - -MT safe. - - - - - - - a #GstHarness - - - - a #gboolean specifying to drop outgoing buffers or not - - - - - - As a convenience, a src-harness will forward %GST_EVENT_STREAM_START, -%GST_EVENT_CAPS and %GST_EVENT_SEGMENT to the main-harness if forwarding -is enabled, and forward any sticky-events from the main-harness to -the sink-harness. It will also forward the %GST_QUERY_ALLOCATION. - -If forwarding is disabled, the user will have to either manually push -these events from the src-harness using gst_harness_src_push_event(), or -create and push them manually. While this will allow full control and -inspection of these events, for the most cases having forwarding enabled -will be sufficient when writing a test where the src-harness' main function -is providing data for the main-harness. - -Forwarding is enabled by default. - -MT safe. - - - - - - - a #GstHarness - - - - a #gboolean to enable/disable forwarding - - - - - - Sets the @allocator and @params to propose when receiving an allocation -query. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstAllocator - - - - a #GstAllocationParams - - - - - - Sets the @GstHarness sinkpad caps. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstCaps to set on the harness sinkpad - - - - - - Sets the @GstHarness sinkpad caps using a string. - -MT safe. - - - - - - - a #GstHarness - - - - a @gchar describing a #GstCaps to set on the harness sinkpad - - - - - - Sets the @GstHarness srcpad caps. This must be done before any buffers -can legally be pushed from the harness to the element. - -MT safe. - - - - - - - a #GstHarness - - - - a #GstCaps to set on the harness srcpad - - - - - - Sets the @GstHarness srcpad caps using a string. This must be done before -any buffers can legally be pushed from the harness to the element. - -MT safe. - - - - - - - a #GstHarness - - - - a @gchar describing a #GstCaps to set on the harness srcpad - - - - - - Advance the #GstTestClock to a specific time. - -MT safe. - - - a @gboolean %TRUE if the time could be set. %FALSE if not. - - - - - a #GstHarness - - - - a #GstClockTime to advance the clock to - - - - - - Sets the min latency reported by #GstHarness when receiving a latency-query - - - - - - - a #GstHarness - - - - a #GstClockTime specifying the latency - - - - - - Convenience that calls gst_harness_push_to_sink @pushes number of times. -Will abort the pushing if any one push fails. - -MT safe. - - - a #GstFlowReturn with the result of the push - - - - - a #GstHarness - - - - a #gint with the number of calls to gst_harness_push_to_sink - - - - - - Transfer data from the src-#GstHarness to the main-#GstHarness. Similar to -gst_harness_push_from_src, this variant allows you to specify how many cranks -and how many pushes to perform. This can be useful for both moving a lot -of data at the same time, as well as cases when one crank does not equal one -buffer to push and v.v. - -MT safe. - - - a #GstFlowReturn with the result of the push - - - - - a #GstHarness - - - - a #gint with the number of calls to gst_harness_crank_single_clock_wait - - - - a #gint with the number of calls to gst_harness_push - - - - - - Similar to what gst_harness_src_push does with #GstBuffers, this transfers -a #GstEvent from the src-#GstHarness to the main-#GstHarness. Note that -some #GstEvents are being transferred automagically. Look at sink_forward_pad -for details. - -MT safe. - - - a #gboolean with the result of the push - - - - - a #GstHarness - - - - - - Start a custom stress-thread that will call your @callback for every -iteration allowing you to do something nasty. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GFunc that is called initially and only once - - - - a #GFunc that is called as often as possible - - - - a #gpointer with custom data to pass to the @callback function - - - - a #gulong specifying how long to sleep in (microseconds) for -each call to the @callback - - - - - - Call g_object_set with @name and @value in intervals of @sleep microseconds - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #gchar specifying a property name - - - - a #GValue to set the property to - - - - a #gulong specifying how long to sleep in (microseconds) for -each g_object_set with @name and @value - - - - - - Push a #GstBuffer in intervals of @sleep microseconds. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstCaps for the #GstBuffer - - - - a #GstSegment - - - - a #GstBuffer to push - - - - a #gulong specifying how long to sleep in (microseconds) for -each call to gst_pad_push - - - - - - Push a #GstBuffer returned by @func in intervals of @sleep microseconds. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstCaps for the #GstBuffer - - - - a #GstSegment - - - - a #GstHarnessPrepareBufferFunc function called before every iteration -to prepare / create a #GstBuffer for pushing - - - - a #gpointer with data to the #GstHarnessPrepareBufferFunc function - - - - a #GDestroyNotify that is called when thread is stopped - - - - a #gulong specifying how long to sleep in (microseconds) for -each call to gst_pad_push - - - - - - Push the @event onto the harnessed #GstElement sinkpad in intervals of -@sleep microseconds - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstEvent to push - - - - a #gulong specifying how long to sleep in (microseconds) for -each gst_event_push with @event - - - - - - Push a #GstEvent returned by @func onto the harnessed #GstElement sinkpad -in intervals of @sleep microseconds. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstHarnessPrepareEventFunc function called before every iteration -to prepare / create a #GstEvent for pushing - - - - a #gpointer with data to the #GstHarnessPrepareEventFunc function - - - - a #GDestroyNotify that is called when thread is stopped - - - - a #gulong specifying how long to sleep in (microseconds) for -each call to gst_pad_push - - - - - - Push the @event onto the harnessed #GstElement srcpad in intervals of -@sleep microseconds. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstEvent to push - - - - a #gulong specifying how long to sleep in (microseconds) for -each gst_event_push with @event - - - - - - Push a #GstEvent returned by @func onto the harnessed #GstElement srcpad -in intervals of @sleep microseconds. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstHarnessPrepareEventFunc function called before every iteration -to prepare / create a #GstEvent for pushing - - - - a #gpointer with data to the #GstHarnessPrepareEventFunc function - - - - a #GDestroyNotify that is called when thread is stopped - - - - a #gulong specifying how long to sleep in (microseconds) for -each call to gst_pad_push - - - - - - Call gst_element_request_pad in intervals of @sleep microseconds - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #GstPadTemplate - - - - a #gchar - - - - a #GstCaps - - - - a #gboolean - - - - a #gulong specifying how long to sleep in (microseconds) for -each gst_element_request_pad - - - - - - Change the state of your harnessed #GstElement from NULL to PLAYING and -back again, only pausing for @sleep microseconds every time. - -MT safe. - - - a #GstHarnessThread - - - - - a #GstHarness - - - - a #gulong specifying how long to sleep in (microseconds) for -each state-change - - - - - - Pulls all pending data from the harness and returns it as a single -data slice. - - - a pointer to the data, newly allocated. Free - with g_free() when no longer needed. Will return %NULL if there is no - data. - - - - - a #GstHarness - - - - the size of the data in bytes - - - - - - Pulls all pending data from the harness and returns it as a single buffer. - - - the data as a buffer. Unref with gst_buffer_unref() - when no longer needed. - - - - - a #GstHarness - - - - - - Pulls all pending data from the harness and returns it as a single #GBytes. - - - a pointer to the data, newly allocated. Free - with g_free() when no longer needed. - - - - - a #GstHarness - - - - - - Tears down a @GstHarness, freeing all resources allocated using it. - -MT safe. - - - - - - - a #GstHarness - - - - - - Pulls a #GstBuffer from the #GAsyncQueue on the #GstHarness sinkpad. Unlike -gst_harness_pull this will not wait for any buffers if not any are present, -and return %NULL straight away. - -MT safe. - - - a #GstBuffer or %NULL if no buffers are present in the #GAsyncQueue - - - - - a #GstHarness - - - - - - Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness sinkpad. -See gst_harness_try_pull for details. - -MT safe. - - - a #GstEvent or %NULL if no buffers are present in the #GAsyncQueue - - - - - a #GstHarness - - - - - - Pulls an #GstEvent from the #GAsyncQueue on the #GstHarness srcpad. -See gst_harness_try_pull for details. - -MT safe. - - - a #GstEvent or %NULL if no buffers are present in the #GAsyncQueue - - - - - a #GstHarness - - - - - - The number of #GstEvents currently in the #GstHarness srcpad #GAsyncQueue - -MT safe. - - - a #guint number of events in the queue - - - - - a #GstHarness - - - - - - The total number of #GstEvents that has arrived on the #GstHarness srcpad -This number includes events handled by the harness as well as events -that have already been pulled out. - -MT safe. - - - a #guint number of events received - - - - - a #GstHarness - - - - - - Sets the system #GstClock on the @GstHarness #GstElement - -MT safe. - - - - - - - a #GstHarness - - - - - - Sets the #GstTestClock on the #GstHarness #GstElement - -MT safe. - - - - - - - a #GstHarness - - - - - - Waits for @timeout seconds until @waits number of #GstClockID waits is -registered with the #GstTestClock. Useful for writing deterministic tests, -where you want to make sure that an expected number of waits have been -reached. - -MT safe. - - - a @gboolean %TRUE if the waits have been registered, %FALSE if not. -(Could be that it timed out waiting or that more waits than waits was found) - - - - - a #GstHarness - - - - a #guint describing the numbers of #GstClockID registered with -the #GstTestClock - - - - a #guint describing how many seconds to wait for @waits to be true - - - - - - Creates a new harness. Works like gst_harness_new_with_padnames(), except it -assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - - - Creates a new empty harness. Use gst_harness_add_element_full() to add -an #GstElement to it. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - Creates a new harness. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #GstElement to attach the harness to (transfer none) - - - - a #GstStaticPadTemplate describing the harness srcpad. -%NULL will not create a harness srcpad. - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. Can be a static or request -or a sometimes pad that has been added. %NULL will not get/request a sinkpad -from the element. (Like if the element is a src.) - - - - a #GstStaticPadTemplate describing the harness sinkpad. -%NULL will not create a harness sinkpad. - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad, similar to the -@element_sinkpad_name. - - - - - - Creates a new harness, parsing the @launchline and putting that in a #GstBin, -and then attches the harness to the bin. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing a gst-launch type line - - - - - - Creates a new harness. Works in the same way as gst_harness_new_full(), only -that generic padtemplates are used for the harness src and sinkpads, which -will be sufficient in most usecases. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #GstElement to attach the harness to (transfer none) - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. %NULL does not attach a -sinkpad - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad. %NULL does not attach a -srcpad - - - - - - Creates a new harness. Works like gst_harness_new_with_element(), -except you specify the factoryname of the #GstElement - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. %NULL does not attach a -sinkpad - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad. %NULL does not attach a -srcpad - - - - - - Creates a new harness, like gst_harness_new_full(), except it -assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - a #GstStaticPadTemplate describing the harness srcpad. -%NULL will not create a harness srcpad. - - - - a #GstStaticPadTemplate describing the harness sinkpad. -%NULL will not create a harness sinkpad. - - - - - - Stop the running #GstHarnessThread - -MT safe. - - - - - - - a #GstHarnessThread - - - - - - - - - - - - - a #GstHarness - - - - user data - - - - - - - - - - - - a #GstHarness - - - - user data - - - - - - - - - Opaque handle representing a GstHarness stress testing thread. - - - - - - - - - - - - - - - - - - Opaque consistency checker handle. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GstTestClock is an implementation of #GstClock which has different -behaviour compared to #GstSystemClock. Time for #GstSystemClock advances -according to the system time, while time for #GstTestClock changes only -when gst_test_clock_set_time() or gst_test_clock_advance_time() are -called. #GstTestClock provides unit tests with the possibility to -precisely advance the time in a deterministic manner, independent of the -system time or any other external factors. - -## Advancing the time of a #GstTestClock - -|[<!-- language="C" --> - #include <gst/gst.h> - #include <gst/check/gsttestclock.h> - - GstClock *clock; - GstTestClock *test_clock; - - clock = gst_test_clock_new (); - test_clock = GST_TEST_CLOCK (clock); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - g_usleep (10 * G_USEC_PER_SEC); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - gst_test_clock_set_time (test_clock, 42 * GST_SECOND); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - ... -]| - -#GstClock allows for setting up single shot or periodic clock notifications -as well as waiting for these notifications synchronously (using -gst_clock_id_wait()) or asynchronously (using gst_clock_id_wait_async() or -gst_clock_id_wait_async()). This is used by many GStreamer elements, -among them #GstBaseSrc and #GstBaseSink. - -#GstTestClock keeps track of these clock notifications. By calling -gst_test_clock_wait_for_next_pending_id() or -gst_test_clock_wait_for_multiple_pending_ids() a unit tests may wait for the -next one or several clock notifications to be requested. Additionally unit -tests may release blocked waits in a controlled fashion by calling -gst_test_clock_process_next_clock_id(). This way a unit test can control the -inaccuracy (jitter) of clock notifications, since the test can decide to -release blocked waits when the clock time has advanced exactly to, or past, -the requested clock notification time. - -There are also interfaces for determining if a notification belongs to a -#GstTestClock or not, as well as getting the number of requested clock -notifications so far. - -N.B.: When a unit test waits for a certain amount of clock notifications to -be requested in gst_test_clock_wait_for_next_pending_id() or -gst_test_clock_wait_for_multiple_pending_ids() then these functions may block -for a long time. If they block forever then the expected clock notifications -were never requested from #GstTestClock, and so the assumptions in the code -of the unit test are wrong. The unit test case runner in gstcheck is -expected to catch these cases either by the default test case timeout or the -one set for the unit test by calling tcase_set_timeout\(\). - -The sample code below assumes that the element under test will delay a -buffer pushed on the source pad by some latency until it arrives on the sink -pad. Moreover it is assumed that the element will at some point call -gst_clock_id_wait() to synchronously wait for a specific time. The first -buffer sent will arrive exactly on time only delayed by the latency. The -second buffer will arrive a little late (7ms) due to simulated jitter in the -clock notification. - -## Demonstration of how to work with clock notifications and #GstTestClock - -|[<!-- language="C" --> - #include <gst/gst.h> - #include <gst/check/gstcheck.h> - #include <gst/check/gsttestclock.h> - - GstClockTime latency; - GstElement *element; - GstPad *srcpad; - GstClock *clock; - GstTestClock *test_clock; - GstBuffer buf; - GstClockID pending_id; - GstClockID processed_id; - - latency = 42 * GST_MSECOND; - element = create_element (latency, ...); - srcpad = get_source_pad (element); - - clock = gst_test_clock_new (); - test_clock = GST_TEST_CLOCK (clock); - gst_element_set_clock (element, clock); - - GST_INFO ("Set time, create and push the first buffer\n"); - gst_test_clock_set_time (test_clock, 0); - buf = create_test_buffer (gst_clock_get_time (clock), ...); - gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); - - GST_INFO ("Block until element is waiting for a clock notification\n"); - gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); - GST_INFO ("Advance to the requested time of the clock notification\n"); - gst_test_clock_advance_time (test_clock, latency); - GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); - processed_id = gst_test_clock_process_next_clock_id (test_clock); - g_assert (processed_id == pending_id); - g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); - gst_clock_id_unref (pending_id); - gst_clock_id_unref (processed_id); - - GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); - g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); - buf = get_buffer_pushed_by_element (element, ...); - g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency); - gst_buffer_unref (buf); - GST_INFO ("Check that element does not wait for any clock notification\n"); - g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); - - GST_INFO ("Set time, create and push the second buffer\n"); - gst_test_clock_advance_time (test_clock, 10 * GST_SECOND); - buf = create_test_buffer (gst_clock_get_time (clock), ...); - gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); - - GST_INFO ("Block until element is waiting for a new clock notification\n"); - (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); - GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n"); - gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND); - GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); - processed_id = gst_test_clock_process_next_clock_id (test_clock); - g_assert (processed_id == pending_id); - g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); - gst_clock_id_unref (pending_id); - gst_clock_id_unref (processed_id); - - GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); - g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); - buf = get_buffer_pushed_by_element (element, ...); - g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, - 10 * GST_SECOND + latency + 7 * GST_MSECOND); - gst_buffer_unref (buf); - GST_INFO ("Check that element does not wait for any clock notification\n"); - g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); - ... -]| - -Since #GstTestClock is only supposed to be used in unit tests it calls -g_assert(), g_assert_cmpint() or g_assert_cmpuint() to validate all function -arguments. This will highlight any issues with the unit test code itself. - - - Creates a new test clock with its time set to zero. - -MT safe. - - - a #GstTestClock cast to #GstClock. - - - - - Creates a new test clock with its time set to the specified time. - -MT safe. - - - a #GstTestClock cast to #GstClock. - - - - - a #GstClockTime set to the desired start time of the clock. - - - - - - Finds the latest time inside the list. - -MT safe. - - - - - - - List - of of pending #GstClockIDs - - - - - - - - Advances the time of the @test_clock by the amount given by @delta. The -time of @test_clock is monotonically increasing, therefore providing a -@delta which is negative or zero is a programming error. - -MT safe. - - - - - - - a #GstTestClock for which to increase the time - - - - a positive #GstClockTimeDiff to be added to the time of the clock - - - - - - A "crank" consists of three steps: -1: Wait for a #GstClockID to be registered with the #GstTestClock. -2: Advance the #GstTestClock to the time the #GstClockID is waiting, unless - the clock time is already passed the clock id (Since: 1.18). -3: Release the #GstClockID wait. -A "crank" can be though of as the notion of -manually driving the clock forward to its next logical step. - - - %TRUE if the crank was successful, %FALSE otherwise. - -MT safe. - - - - - #GstTestClock to crank - - - - - - Retrieve the requested time for the next pending clock notification. - -MT safe. - - - a #GstClockTime set to the time of the next pending clock -notification. If no clock notifications have been requested -%GST_CLOCK_TIME_NONE will be returned. - - - - - a #GstTestClock to fetch the next clock notification time for - - - - - - Checks whether @test_clock was requested to provide the clock notification -given by @id. - -MT safe. - - - %TRUE if the clock has been asked to provide the given clock -notification, %FALSE otherwise. - - - - - a #GstTestClock to ask if it provided the notification - - - - a #GstClockID clock notification - - - - - - Determine the number of pending clock notifications that have been -requested from the @test_clock. - -MT safe. - - - the number of pending clock notifications. - - - - - a #GstTestClock for which to count notifications - - - - - - Determines if the @pending_id is the next clock notification scheduled to -be triggered given the current time of the @test_clock. - -MT safe. - - - %TRUE if @pending_id is the next clock notification to be -triggered, %FALSE otherwise. - - - - - a #GstTestClock to check the clock notifications for - - - - a #GstClockID clock -notification to look for - - - - - - Processes and releases the pending ID. - -MT safe. - - - - - - - #GstTestClock for which to process the pending IDs - - - - #GstClockID - - - - - - Processes and releases the pending IDs in the list. - -MT safe. - - - - - - - #GstTestClock for which to process the pending IDs - - - - List - of pending #GstClockIDs - - - - - - - - MT safe. - - - a #GstClockID containing the next pending clock -notification. - - - - - a #GstTestClock for which to retrieve the next pending clock -notification - - - - - - Sets the time of @test_clock to the time given by @new_time. The time of -@test_clock is monotonically increasing, therefore providing a @new_time -which is earlier or equal to the time of the clock as given by -gst_clock_get_time() is a programming error. - -MT safe. - - - - - - - a #GstTestClock of which to set the time - - - - a #GstClockTime later than that returned by gst_clock_get_time() - - - - - - Blocks until at least @count clock notifications have been requested from -@test_clock, or the timeout expires. - -MT safe. - - - a @gboolean %TRUE if the waits have been registered, %FALSE if not. -(Could be that it timed out waiting or that more waits than waits was found) - - - - - #GstTestClock for which to await having enough pending clock - - - - the number of pending clock notifications to wait for - - - - the timeout in milliseconds - - - - Address - of a #GList pointer variable to store the list of pending #GstClockIDs - that expired, or %NULL - - - - - - - - Blocks until at least @count clock notifications have been requested from -@test_clock. There is no timeout for this wait, see the main description of -#GstTestClock. - -MT safe. - - - - - - - #GstTestClock for which to await having enough pending clock - - - - the number of pending clock notifications to wait for - - - - Address - of a #GList pointer variable to store the list of pending #GstClockIDs - that expired, or %NULL - - - - - - - - Waits until a clock notification is requested from @test_clock. There is no -timeout for this wait, see the main description of #GstTestClock. A reference -to the pending clock notification is stored in @pending_id. - -MT safe. - - - - - - - #GstTestClock for which to get the pending clock notification - - - - #GstClockID -with information about the pending clock notification - - - - - - Blocks until at least @count clock notifications have been requested from -@test_clock. There is no timeout for this wait, see the main description of -#GstTestClock. - use gst_test_clock_wait_for_multiple_pending_ids() instead. - - - - - - - #GstTestClock for which to await having enough pending clock - - - - the number of pending clock notifications to wait for - - - - - - - - - When a #GstTestClock is constructed it will have a certain start time set. -If the clock was created using gst_test_clock_new_with_start_time() then -this property contains the value of the @start_time argument. If -gst_test_clock_new() was called the clock started at time zero, and thus -this property contains the value 0. - - - - - - - - - - - The class of a #GstTestClock, which has no virtual methods to override. - - - the parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Sets up a data probe on the given pad which will raise assertions if the -data flow is inconsistent. - - - %TRUE if the pad was added - - - - - The #GstStreamConsistency handle - - - - The #GstPad on which the dataflow will be checked. - - - - - - Frees the allocated data and probes associated with @consist. - - - - - - - The #GstStreamConsistency to free. - - - - - - Sets up a data probe on the given pad which will raise assertions if the -data flow is inconsistent. - - - A #GstStreamConsistency structure used to track data flow. - - - - - The #GstPad on which the dataflow will be checked. - - - - - - Reset the stream checker's internal variables. - - - - - - - The #GstStreamConsistency to reset. - - - - - - Creates a new harness. Works like gst_harness_new_with_padnames(), except it -assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - - - Creates a new empty harness. Use gst_harness_add_element_full() to add -an #GstElement to it. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - Creates a new harness. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #GstElement to attach the harness to (transfer none) - - - - a #GstStaticPadTemplate describing the harness srcpad. -%NULL will not create a harness srcpad. - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. Can be a static or request -or a sometimes pad that has been added. %NULL will not get/request a sinkpad -from the element. (Like if the element is a src.) - - - - a #GstStaticPadTemplate describing the harness sinkpad. -%NULL will not create a harness sinkpad. - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad, similar to the -@element_sinkpad_name. - - - - - - Creates a new harness, parsing the @launchline and putting that in a #GstBin, -and then attches the harness to the bin. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing a gst-launch type line - - - - - - Creates a new harness. Works in the same way as gst_harness_new_full(), only -that generic padtemplates are used for the harness src and sinkpads, which -will be sufficient in most usecases. - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #GstElement to attach the harness to (transfer none) - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. %NULL does not attach a -sinkpad - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad. %NULL does not attach a -srcpad - - - - - - Creates a new harness. Works like gst_harness_new_with_element(), -except you specify the factoryname of the #GstElement - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - a #gchar with the name of the element -sinkpad that is then linked to the harness srcpad. %NULL does not attach a -sinkpad - - - - a #gchar with the name of the element -srcpad that is then linked to the harness sinkpad. %NULL does not attach a -srcpad - - - - - - Creates a new harness, like gst_harness_new_full(), except it -assumes the #GstElement sinkpad is named "sink" and srcpad is named "src" - -MT safe. - - - a #GstHarness, or %NULL if the harness could -not be created - - - - - a #gchar describing the #GstElement name - - - - a #GstStaticPadTemplate describing the harness srcpad. -%NULL will not create a harness srcpad. - - - - a #GstStaticPadTemplate describing the harness sinkpad. -%NULL will not create a harness sinkpad. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Stop the running #GstHarnessThread - -MT safe. - - - - - - - a #GstHarnessThread - - - - - - diff --git a/gir-files/GstController-1.0.gir b/gir-files/GstController-1.0.gir deleted file mode 100644 index bd8460f3a..000000000 --- a/gir-files/GstController-1.0.gir +++ /dev/null @@ -1,1075 +0,0 @@ - - - - - - - - - - - - A value mapping object that attaches multiple control sources to a guint -gobject properties representing a color. A control value of 0.0 will turn the -color component off and a value of 1.0 will be the color level. - - - Create a new control-binding that attaches the given #GstControlSource to the -#GObject property. - - - the new #GstARGBControlBinding - - - - - the object of the property - - - - the property-name to attach the control source - - - - the control source for the alpha channel - - - - the control source for the red channel - - - - the control source for the green channel - - - - the control source for the blue channel - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The class structure of #GstARGBControlBinding. - - - Parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An internal structure for value+time and various temporary -values used for interpolation. This "inherits" from -GstTimedValue. - - - timestamp of the value change - - - - the new value - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Copies a #GstControlPoint - - - A copy of @cp - - - - - The control point to copy - - - - - - Frees all data allocated by a #GstControlPoint instance. - - - - - - - the object to free - - - - - - - - - - - - - - - - - - - - - - - - - - - - A value mapping object that attaches control sources to gobject properties. It -will map the control values directly to the target property range. If a -non-absolute direct control binding is used, the value range [0.0 ... 1.0] -is mapped to full target property range, and all values outside the range -will be clipped. An absolute control binding will not do any value -transformations. - - - Create a new control-binding that attaches the #GstControlSource to the -#GObject property. It will map the control source range [0.0 ... 1.0] to -the full target property range, and clip all values outside this range. - - - the new #GstDirectControlBinding - - - - - the object of the property - - - - the property-name to attach the control source - - - - the control source - - - - - - Create a new control-binding that attaches the #GstControlSource to the -#GObject property. It will directly map the control source values to the -target property range without any transformations. - - - the new #GstDirectControlBinding - - - - - the object of the property - - - - the property-name to attach the control source - - - - the control source - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The class structure of #GstDirectControlBinding. - - - Parent class - - - - - - - - - - Function to map a control-value to the target GValue. - - - - - - - the #GstDirectControlBinding instance - - - - the value returned by the cotnrol source - - - - the target GValue - - - - - - Function to map a control-value to the target plain data type. - - - - - - - the #GstDirectControlBinding instance - - - - the value returned by the cotnrol source - - - - the target location - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstInterpolationControlSource is a #GstControlSource, that interpolates values between user-given -control points. It supports several interpolation modes and property types. - -To use #GstInterpolationControlSource get a new instance by calling -gst_interpolation_control_source_new(), bind it to a #GParamSpec and set some -control points by calling gst_timed_value_control_source_set(). - -All functions are MT-safe. - - - This returns a new, unbound #GstInterpolationControlSource. - - - a new, unbound #GstInterpolationControlSource. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The various interpolation modes available. - - steps-like interpolation, default - - - linear interpolation - - - cubic interpolation (natural), may overshoot - the min or max values set by the control point, but is more 'curvy' - - - monotonic cubic interpolation, will not - produce any values outside of the min-max range set by the control points - (Since: 1.8) - - - - #GstLFOControlSource is a #GstControlSource, that provides several periodic -waveforms as control values. - -To use #GstLFOControlSource get a new instance by calling -gst_lfo_control_source_new(), bind it to a #GParamSpec and set the relevant -properties. - -All functions are MT-safe. - - - This returns a new, unbound #GstLFOControlSource. - - - a new, unbound #GstLFOControlSource. - - - - - Specifies the amplitude for the waveform of this #GstLFOControlSource. - - - - Specifies the frequency that should be used for the waveform -of this #GstLFOControlSource. It should be large enough -so that the period is longer than one nanosecond. - - - - Specifies the value offset for the waveform of this #GstLFOControlSource. - - - - Specifies the timeshift to the right that should be used for the waveform -of this #GstLFOControlSource in nanoseconds. - -To get a n nanosecond shift to the left use -"(GST_SECOND / frequency) - n". - - - - Specifies the waveform that should be used for this #GstLFOControlSource. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The various waveform modes available. - - sine waveform - - - square waveform - - - saw waveform - - - reverse saw waveform - - - triangle waveform - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GstControlBinding that forwards requests to another #GstControlBinding - - - #GstProxyControlBinding forwards all access to data or `sync_values()` -requests from @property_name on @object to the control binding at -@ref_property_name on @ref_object. - - - a new #GstControlBinding that proxies the control interface between -properties on different #GstObject's - - - - - a #GstObject - - - - the property name in @object to control - - - - a #GstObject to forward all - #GstControlBinding requests to - - - - the property_name in @ref_object to control - - - - - - - - - - - - - - - - - - - - - Opaque #GstProxyControlBindingClass struct - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for #GstControlSource that use time-stamped values. - -When overriding bind, chain up first to give this bind implementation a -chance to setup things. - -All functions are MT-safe. - - - Find last value before given timestamp in control point list. -If all values in the control point list come after the given -timestamp or no values exist, %NULL is returned. - -For use in control source implementations. - - - the found #GSequenceIter or %NULL - - - - - the control source to search in - - - - the search key - - - - - - Returns a read-only copy of the list of #GstTimedValue for the given property. -Free the list after done with it. - - - a copy -of the list, or %NULL if the property isn't handled by the controller - - - - - - - the #GstTimedValueControlSource to get the list from - - - - - - Get the number of control points that are set. - - - the number of control points that are set. - - - - - the #GstTimedValueControlSource to get the number of values from - - - - - - Set the value of given controller-handled property at a certain time. - - - FALSE if the values couldn't be set, TRUE otherwise. - - - - - the #GstTimedValueControlSource object - - - - the time the control-change is scheduled for - - - - the control-value - - - - - - Sets multiple timed values at once. - - - FALSE if the values couldn't be set, TRUE otherwise. - - - - - the #GstTimedValueControlSource object - - - - a list -with #GstTimedValue items - - - - - - - - Used to remove the value of given controller-handled property at a certain -time. - - - FALSE if the value couldn't be unset (i.e. not found, TRUE otherwise. - - - - - the #GstTimedValueControlSource object - - - - the time the control-change should be removed from - - - - - - Used to remove all time-stamped values of given controller-handled property - - - - - - - the #GstTimedValueControlSource object - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Emitted right after the new value has been added to @self - - - - - - The newly added #GstTimedValue - - - - - - Emitted right after the new value has been set on @timed_signals - - - - - - The #GstTimedValue where the value changed - - - - - - Emitted when @timed_value is removed from @self - - - - - - The removed #GstTimedValue - - - - - - - - - - - - - - - - - - - - - #GstTriggerControlSource is a #GstControlSource, that returns values from user-given -control points. It allows for a tolerance on the time-stamps. - -To use #GstTriggerControlSource get a new instance by calling -gst_trigger_control_source_new(), bind it to a #GParamSpec and set some -control points by calling gst_timed_value_control_source_set(). - -All functions are MT-safe. - - - This returns a new, unbound #GstTriggerControlSource. - - - a new, unbound #GstTriggerControlSource. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Reset the controlled value cache. - - - - - - - the #GstTimedValueControlSource - - - - - - diff --git a/gir-files/GstGL-1.0.gir b/gir-files/GstGL-1.0.gir deleted file mode 100644 index d1f74a4fe..000000000 --- a/gir-files/GstGL-1.0.gir +++ /dev/null @@ -1,11015 +0,0 @@ - - - - - - - - - - - An option that can be activated on bufferpools to request OpenGL -synchronization metadata on buffers from the pool. - - - - - String used for %GST_GL_TEXTURE_TARGET_2D as a #GstBufferPool pool option - - - - - String used for %GST_GL_TEXTURE_TARGET_EXTERNAL_OES as a #GstBufferPool pool option - - - - - String used for %GST_GL_TEXTURE_TARGET_RECTANGLE as a #GstBufferPool pool option - - - - - Name of the caps feature indicating the use of GL buffers - - - - - Name of the caps feature for indicating the use of #GstGLMemory - - - - - - no API - - - Desktop OpenGL up to and including 3.1. The - compatibility profile when the OpenGL version is >= 3.2 - - - Desktop OpenGL >= 3.2 core profile - - - OpenGL ES 1.x - - - OpenGL ES 2.x and 3.x - - - Any OpenGL API - - - - - The #GstGLAPI represented by @api_s - - - - - a space separated string of OpenGL apis - - - - - - - - A space separated string of the OpenGL api's enabled in @api - - - - - a #GstGLAPI to stringify - - - - - - - - - the size of the struct (including and subclass data) - - - - a #GstGLAllocationParamsCopyFunc - - - - a #GstGLAllocationParamsFreeFunc - - - - allocation flags - - - - the allocation size - - - - the #GstAllocationParams - - - - a #GstGLContext - - - - a #GDestroyNotify - - - - argument to call @notify with - - - - the wrapped data pointer - - - - the wrapped OpenGL handle - - - - - - - - - - - a copy of the #GstGLAllocationParams specified by - @src or %NULL on failure - - - - - the #GstGLAllocationParams to initialize - - - - - - Copies the dynamically allocated data from @src to @dest. Direct subclasses -should call this function in their own overridden copy function. - - - - - - - the source #GstGLAllocationParams - - - - the destination #GstGLAllocationParams - - - - - - Frees the #GstGLAllocationParams and all associated data. - - - - - - - the #GstGLAllocationParams to initialize - - - - - - Frees the dynamically allocated data in @params. Direct subclasses -should call this function in their own overridden free function. - - - - - - - the source #GstGLAllocationParams - - - - - - @notify will be called once for each allocated memory using these @params -when freeing the memory. - - - whether the parameters could be initialized - - - - - the #GstGLAllocationParams to initialize - - - - the struct size of the implementation - - - - some alloc flags - - - - a copy function - - - - a free function - - - - a #GstGLContext - - - - the number of bytes to allocate. - - - - a #GstAllocationParams to apply - - - - a sysmem data pointer to initialize the allocation with - - - - a GL handle to initialize the allocation with - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - - Copies the parameters from @src into @dest. The subclass must compose copy -functions from the superclass. - - - - - - - the source #GstGLAllocationParams to copy from - - - - the source #GstGLAllocationParams to copy - - - - - - Free any dynamically allocated data. The subclass must call the superclass' -free. - - - - - - - a #GstGLAllocationParams - - - - - - #GstGLAsyncDebug an opaque structure and should only be accessed through the -provided API. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Frees @ad - - - - - - - a #GstGLAsyncDebug - - - - - - freeze the debug output. While frozen, any call to -gst_gl_async_debug_output_log_msg() will not output any messages but -subsequent calls to gst_gl_async_debug_store_log_msg() will overwrite previous -messages. - - - - - - - a #GstGLAsyncDebug - - - - - - Initialize @ad. Intended for use with #GstGLAsyncDebug's that are embedded -in other structs. - - - - - - - a #GstGLAsyncDebug - - - - - - Outputs a previously stored debug message. - - - - - - - the #GstGLAsyncDebug to store the message in - - - - - - Stores a debug message for later output by gst_gl_async_debug_output_log_msg() - - - - - - - the #GstGLAsyncDebug to store the message in - - - - the #GstDebugCategory to output the message in - - - - the #GstDebugLevel - - - - the file where the debug message originates from - - - - the function where the debug message originates from - - - - the line in @file where the debug message originates from - - - - a #GObject to associate with the debug message - - - - a printf style format string - - - - the list of arguments for @format - - - - - - Stores a debug message for later output by gst_gl_async_debug_output_log_msg() - - - - - - - the #GstGLAsyncDebug to store the message in - - - - the #GstDebugCategory to output the message in - - - - the #GstDebugLevel - - - - the file where the debug message originates from - - - - the function where the debug message originates from - - - - the line in @file where the debug message originates from - - - - a #GObject to associate with the debug message - - - - a printf style format string - - - - the list of arguments for @format - - - - - - unfreeze the debug output. See gst_gl_async_debug_freeze() for what freezing means - - - - - - - a #GstGLAsyncDebug - - - - - - Unset any dynamically allocated data. Intended for use with -#GstGLAsyncDebug's that are embedded in other structs. - - - - - - - a #GstGLAsyncDebug - - - - - - Free with gst_gl_async_debug_free() - - - a new #GstGLAsyncDebug - - - - - - - - - - - - - - - - - #GstGLBaseFilter handles the nitty gritty details of retrieving an OpenGL -context. It also provided some wrappers around #GstBaseTransform's -`start()`, `stop()` and `set_caps()` virtual methods that ensure an OpenGL -context is available and current in the calling thread. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Whether an OpenGL context could be retrieved or created successfully - - - - - a #GstGLBaseFilter - - - - - - - - the #GstGLContext found by @filter - - - - - a #GstGLBaseFilter - - - - - - - - - - - - the currently configured #GstGLDisplay - - - - the currently configured #GstGLContext - - - - the currently configured input #GstCaps - - - - the currently configured output #GstCaps - - - - - - - - - - - - - The base class for GStreamer GL Filter. - - - - - - the logical-OR of #GstGLAPI's supported by this element - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GstGLBaseMemory is a #GstMemory subclass providing the basis of support -for the mapping of GL buffers. - -Data is uploaded or downloaded from the GPU as is necessary. - - - the parent object - - - - the #GstGLContext to use for GL operations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Note: only intended for subclass usage to allocate the system memory buffer -on demand. If there is already a non-NULL data pointer in @gl_mem->data, -then this function imply returns TRUE. - - - whether the system memory could be allocated - - - - - a #GstGLBaseMemory - - - - - - Initializes @mem with the required parameters - - - - - - - the #GstGLBaseMemory to initialize - - - - the #GstAllocator to initialize with - - - - the parent #GstMemory to initialize with - - - - the #GstGLContext to initialize with - - - - the @GstAllocationParams to initialize with - - - - the number of bytes to be allocated - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - - - whether the copy succeeded. - - - - - the source #GstGLBaseMemory - - - - the destination #GstGLBaseMemory - - - - the offset to start at - - - - the number of bytes to copy - - - - - - - - a new #GstGLBaseMemory from @allocator with the requested @params. - - - - - a #GstGLBaseMemoryAllocator - - - - the #GstGLAllocationParams to allocate the memory with - - - - - - Initializes the GL Base Memory allocator. It is safe to call this function -multiple times. This must be called before any other GstGLBaseMemory operation. - - - - - - - - Opaque #GstGLBaseMemoryAllocator struct - - - - - a newly allocated #GstGLBaseMemory from @allocator and @params - - - - - a #GstGLBaseMemoryAllocator - - - - the #GstGLAllocationParams to allocate the memory with - - - - - - - - - - - - - - - - - - Note: not called with a GL context current - - - a newly allocated #GstGLBaseMemory from @allocator and @params - - - - - a #GstGLBaseMemoryAllocator - - - - the #GstGLAllocationParams to allocate the memory with - - - - - - - - the parent class - - - - a #GstGLBaseMemoryAllocatorAllocFunction - - - - a #GstGLBaseMemoryAllocatorCreateFunction - - - - a #GstGLBaseMemoryAllocatorMapFunction - - - - a #GstGLBaseMemoryAllocatorUnmapFunction - - - - a #GstGLBaseMemoryAllocatorCopyFunction - - - - a #GstGLBaseMemoryAllocatorDestroyFunction - - - - - - - - - - Also see gst_memory_copy(); - - - the newly copied #GstGLMemory or %NULL - - - - - a #GstGLBaseMemory - - - - the offset to copy from - - - - the number of bytes to copy - - - - - - As this virtual method is called with an OpenGL context current, use this -function to allocate and OpenGL resources needed for your application - - - whether the creation succeeded - - - - - a #GstGLBaseMemory - - - - - - Destroy any resources allocated throughout the lifetime of @mem - - - - - - - a #GstGLBaseMemory - - - - - - Also see gst_memory_map(); - - - the mapped pointer - - - - - a #GstGLBaseMemory - - - - a #GstMapInfo to map with - - - - the size to map - - - - - - Also see gst_memory_unmap(); - - - - - - - a #GstGLBaseMemory - - - - a #GstMapInfo to map with - - - - - - - generic failure - - - the implementation is too old and doesn't - implement enough features - - - a resource could not be found - - - - the quark used for #GstGLBaseMemory in #GError's - - - - - - - the texture needs downloading - to the data pointer - - - the data pointer needs uploading - to the texture - - - - #GstGLBaseSrc handles the nitty gritty details of retrieving an OpenGL -context. It also provided some wrappers around #GstBaseSrc's `start()` and -`stop()` virtual methods that ensure an OpenGL context is available and -current in the calling thread. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the currently configured #GstGLDisplay - - - - the currently configured #GstGLContext - - - - the currently configured output #GstVideoInfo - - - - the currently configured output #GstCaps - - - - the total running time - - - - - - - - - - - - - The base class for GStreamer GL Video sources. - - - - - - the logical-OR of #GstGLAPI's supported by this element - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GstGLBuffer is a #GstMemory subclass providing support for the mapping of -GL buffers. - -Data is uploaded or downloaded from the GPU as is necessary. - - - the parent object - - - - the buffer id for this memory - - - - the OpenGL target of this texture for binding purposes - - - - the OpenGL usage hints this buffer was created with - - - - Initializes the GL Buffer allocator. It is safe to call this function -multiple times. This must be called before any other #GstGLBuffer operation. - - - - - - - - - - parent object - - - - the OpenGL target to bind the buffer to - - - - the OpenGL usage hint to create the buffer with - - - - - - - - - - - a new #GstGLBufferAllocationParams for allocating OpenGL buffer - objects - - - - - a #GstGLContext - - - - the size in bytes to allocate - - - - the #GstAllocationParams for @tex_id - - - - the OpenGL target to allocate - - - - the OpenGL usage hint to allocate with - - - - - - - Opaque #GstGLBufferAllocator struct - - - - - - - - - - - - The #GstGLBufferAllocatorClass only contains private data - - - - - - - - - - - - a #GstGLBufferPool is an object that allocates buffers with #GstGLBaseMemory - -A #GstGLBufferPool is created with gst_gl_buffer_pool_new() - -#GstGLBufferPool implements the VideoMeta buffer pool option -%GST_BUFFER_POOL_OPTION_VIDEO_META, the VideoAligment buffer pool option -%GST_BUFFER_POOL_OPTION_VIDEO_ALIGNMENT as well as the OpenGL specific -%GST_BUFFER_POOL_OPTION_GL_SYNC_META buffer pool option. - - - - - a #GstBufferPool that allocates buffers with #GstGLMemory - - - - - the #GstGLContext to use - - - - - - - - - - - - - - - - - - - - - The #GstGLBufferPoolClass structure contains only private data - - - - - - - - - - - - - - - #GstGLColorConvert is an object that converts between color spaces and/or -formats using OpenGL Shaders. - -A #GstGLColorConvert can be created with gst_gl_color_convert_new(), the -configuration negotiated with gst_gl_color_convert_transform_caps() and the -conversion performed with gst_gl_color_convert_perform(). - -The glcolorconvertelement provides a GStreamer element that uses -#GstGLColorConvert to convert between video formats and color spaces. - - - - - a new #GstGLColorConvert object - - - - - a #GstGLContext - - - - - - Provides an implementation of #GstBaseTransformClass.fixate_caps() - - - the fixated #GstCaps - - - - - a #GstGLContext to use for transforming @caps - - - - a #GstPadDirection - - - - the #GstCaps of @direction - - - - the #GstCaps to fixate - - - - - - Provides an implementation of #GstBaseTransformClass.transform_caps() - - - the converted #GstCaps - - - - - a #GstGLContext to use for transforming @caps - - - - a #GstPadDirection - - - - the #GstCaps to transform - - - - a set of filter #GstCaps - - - - - - Provides an implementation of #GstBaseTransformClass.decide_allocation() - - - whether the allocation parameters were successfully chosen - - - - - a #GstGLColorConvert - - - - a completed ALLOCATION #GstQuery - - - - - - Converts the data contained by @inbuf using the formats specified by the -#GstCaps passed to gst_gl_color_convert_set_caps() - - - a converted #GstBuffer or %NULL - - - - - a #GstGLColorConvert - - - - the #GstGLMemory filled #GstBuffer to convert - - - - - - Initializes @convert with the information required for conversion. - - - - - - - a #GstGLColorConvert - - - - input #GstCaps - - - - output #GstCaps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstGLColorConvertClass struct only contains private data - - - - - - - - - - - - - - - #GstGLContext wraps an OpenGL context object in a uniform API. As a result -of the limitation on OpenGL context, this object is not thread safe unless -specified and must only be activated in a single thread. - - - Create a new #GstGLContext with the specified @display - - - a new #GstGLContext - - - - - a #GstGLDisplay - - - - - - Wraps an existing OpenGL context into a #GstGLContext. - -Note: The caller is responsible for ensuring that the OpenGL context -represented by @handle stays alive while the returned #GstGLContext is -active. - -@context_type must not be %GST_GL_PLATFORM_NONE or %GST_GL_PLATFORM_ANY - -@available_apis must not be %GST_GL_API_NONE or %GST_GL_API_ANY - - - a #GstGLContext wrapping @handle - - - - - a #GstGLDisplay - - - - the OpenGL context to wrap - - - - a #GstGLPlatform specifying the type of context in @handle - - - - a #GstGLAPI containing the available OpenGL apis in @handle - - - - - - A default implementation of the various GetProcAddress functions that looks -for @name in the OpenGL shared libraries or in the current process. - -See also: gst_gl_context_get_proc_address() - - - an address pointing to @name or %NULL - - - - - a #GstGLAPI - - - - then function to get the address of - - - - - - See also gst_gl_context_activate(). - - - the #GstGLContext active in the current thread or %NULL - - - - - If an error occurs, @major and @minor are not modified and %GST_GL_API_NONE is -returned. - - - The version supported by the OpenGL context current in the calling - thread or %GST_GL_API_NONE - - - - - the #GstGLPlatform to retrieve the API for - - - - the major version - - - - the minor version - - - - - - - - The OpenGL context handle current in the calling thread or %NULL - - - - - a #GstGLPlatform specifying the type of context to retrieve - - - - - - Attempts to use the @context_type specific GetProcAddress implementations -to retrieve @name. - -See also gst_gl_context_get_proc_address(). - - - a function pointer for @name, or %NULL - - - - - a #GstGLPlatform - - - - a #GstGLAPI - - - - the name of the function to retrieve - - - - - - (De)activate the OpenGL context represented by this @context. - -In OpenGL terms, calls eglMakeCurrent or similar with this context and the -currently set window. See gst_gl_context_set_window() for details. - - - Whether the activation succeeded - - - - - a #GstGLContext - - - - %TRUE to activate, %FALSE to deactivate - - - - - - Check for an OpenGL @feature being supported. - -Note: Most features require that the context be created before it is -possible to determine their existence and so will fail if that is not the -case. - - - Whether @feature is supported by @context - - - - - a #GstGLContext - - - - a platform specific feature - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the currently enabled OpenGL api. - -The currently available API may be limited by the #GstGLDisplay in use and/or -the #GstGLWindow chosen. - - - the available OpenGL api - - - - - a #GstGLContext - - - - - - Gets the backing OpenGL context used by @context. - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - Gets the OpenGL platform that used by @context. - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - Get the version of the OpenGL platform (GLX, EGL, etc) used. Only valid -after a call to gst_gl_context_create(). - - - - - - - a #GstGLContext - - - - return for the major version - - - - return for the minor version - - - - - - Swap the front and back buffers on the window attached to @context. -This will display the frame on the next refresh cycle. - - - - - - - a #GstGLContext - - - - - - (De)activate the OpenGL context represented by this @context. - -In OpenGL terms, calls eglMakeCurrent or similar with this context and the -currently set window. See gst_gl_context_set_window() for details. - - - Whether the activation succeeded - - - - - a #GstGLContext - - - - %TRUE to activate, %FALSE to deactivate - - - - - - Note: This will always fail for two wrapped #GstGLContext's - - - whether @context and @other_context are able to share OpenGL - resources. - - - - - a #GstGLContext - - - - another #GstGLContext - - - - - - Check for an OpenGL @feature being supported. - -Note: Most features require that the context be created before it is -possible to determine their existence and so will fail if that is not the -case. - - - Whether @feature is supported by @context - - - - - a #GstGLContext - - - - a platform specific feature - - - - - - - - whether whether the current framebuffer is complete - - - - - a #GstGLContext - - - - the GL value of the framebuffer target, GL_FRAMEBUFFER, - GL_READ_FRAMEBUFFER, GL_DRAW_FRAMEBUFFER - - - - - - - - whether OpenGL context implements the required api and specified -version. - - - - - a #GstGLContext - - - - api type required - - - - major version required - - - - minor version required - - - - - - Unbind the current framebuffer - - - - - - - a #GstGLContext - - - - - - Clear's the currently set shader from the GL state machine. - -Note: must be called in the GL thread. - - - - - - - a #GstGLContext - - - - - - Creates an OpenGL context with the specified @other_context as a context -to share shareable OpenGL objects with. See the OpenGL specification for -what is shared between OpenGL contexts. - -If an error occurs, and @error is not %NULL, then error will contain details -of the error and %FALSE will be returned. - -Should only be called once. - - - whether the context could successfully be created - - - - - a #GstGLContext: - - - - a #GstGLContext to share OpenGL objects with - - - - - - Destroys an OpenGL context. - -Should only be called after gst_gl_context_create() has been successfully -called for this context. - - - - - - - a #GstGLContext: - - - - - - Fills @context's info (version, extensions, vtable, etc) from the GL -context in the current thread. Typically used with wrapped contexts to -allow wrapped contexts to be used as regular #GstGLContext's. - - - - - - - a #GstGLContext: - - - - - - - - the #GstGLDisplay associated with this @context - - - - - a #GstGLContext: - - - - - - Get the currently enabled OpenGL api. - -The currently available API may be limited by the #GstGLDisplay in use and/or -the #GstGLWindow chosen. - - - the available OpenGL api - - - - - a #GstGLContext - - - - - - Gets the backing OpenGL context used by @context. - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - Gets the OpenGL platform that used by @context. - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - Get the version of the OpenGL platform (GLX, EGL, etc) used. Only valid -after a call to gst_gl_context_create(). - - - - - - - a #GstGLContext - - - - return for the major version - - - - return for the minor version - - - - - - Returns the OpenGL version implemented by @context. See -gst_gl_context_get_gl_api() for retrieving the OpenGL api implemented by -@context. - - - - - - - a #GstGLContext - - - - resulting major version - - - - resulting minor version - - - - - - Get a function pointer to a specified opengl function, @name. If the the -specific function does not exist, NULL is returned instead. - -Platform specific functions (names starting 'egl', 'glX', 'wgl', etc) can also -be retrieved using this method. - -Note: This function may return valid function pointers that may not be valid -to call in @context. The caller is responsible for ensuring that the -returned function is a valid function to call in @context by either checking -the OpenGL API and version or for an appropriate OpenGL extension. - -Note: On success, you need to cast the returned function pointer to the -correct type to be able to call it correctly. On 32-bit Windows, this will -include the `GSTGLAPI` identifier to use the correct calling convention. -e.g. - -|[<!-- language="C" --> -void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret) -]| - - - a function pointer or %NULL - - - - - a #GstGLContext - - - - an opengl function name - - - - - - - - The #GThread, @context is current in or NULL - - - - - a #GstGLContext - - - - - - - - the currently set window - - - - - a #GstGLContext - - - - - - - - Whether the #GstGLContext has been shared with another #GstGLContext - - - - - a #GstGLContext - - - - - - Will internally set @context as shared with @share - - - - - - - a wrapped #GstGLContext - - - - another #GstGLContext - - - - - - Set's the current window on @context to @window. The window can only be -changed before gst_gl_context_create() has been called and the @window is not -already running. - - - Whether the window was successfully updated - - - - - a #GstGLContext - - - - a #GstGLWindow - - - - - - - - Whether @context supports the combination of @version with @profile - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - - - whether @context supports the 'precision' specifier in GLSL shaders - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - - - whether @context supports the 'precision highp' specifier in GLSL shaders - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - Swap the front and back buffers on the window attached to @context. -This will display the frame on the next refresh cycle. - - - - - - - a #GstGLContext - - - - - - Execute @func in the OpenGL thread of @context with @data - -MT-safe - - - - - - - a #GstGLContext - - - - a #GstGLContextThreadFunc - - - - user data to call @func with - - - - - - - - - - - - - - - a list of OpenGL function pointers - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - - - - - the available OpenGL api - - - - - a #GstGLContext - - - - - - - - - - The platform specific backing OpenGL context - - - - - a #GstGLContext: - - - - - - - - - - - - - - - - - - - - - - - - - - Whether the activation succeeded - - - - - a #GstGLContext - - - - %TRUE to activate, %FALSE to deactivate - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstGLContext - - - - - - - - - - Whether @feature is supported by @context - - - - - a #GstGLContext - - - - a platform specific feature - - - - - - - - - - - - - - a #GstGLContext - - - - return for the major version - - - - return for the minor version - - - - - - - - - - - - - OpenGL context errors. - - Failed for an unspecified reason - - - The configuration requested is not correct - - - The OpenGL API requested is not correct - - - The OpenGL libraries are too old - - - glXCreateContext (or similar) failed - - - A resource is not available - - - - the quark used for #GstGLContext in #GError's - - - - - - - - - Represents a function to run in the GL thread with @context and @data - - - - - - - a #GstGLContext - - - - user data - - - - - - #GstGLDisplay represents a connection to the underlying windowing system. -Elements are required to make use of #GstContext to share and propagate -a #GstGLDisplay. - -There are a number of environment variables that influence the choice of -platform and window system specific functionality. -- GST_GL_WINDOW influences the window system to use. Common values are - 'x11', 'wayland', 'win32' or 'cocoa'. -- GST_GL_PLATFORM influences the OpenGL platform to use. Common values are - 'egl', 'glx', 'wgl' or 'cgl'. -- GST_GL_API influences the OpenGL API requested by the OpenGL platform. - Common values are 'opengl', 'opengl3' and 'gles2'. - -> Certain window systems require a special function to be called to -> initialize threading support. As this GStreamer GL library does not preclude -> concurrent access to the windowing system, it is strongly advised that -> applications ensure that threading support has been initialized before any -> other toolkit/library functionality is accessed. Failure to do so could -> result in sudden application abortion during execution. The most notably -> example of such a function is X11's XInitThreads\(). - - - - - a new #GstGLDisplay - - - - - - - a new #GstGLWindow for @display or %NULL. - - - - - a #GstGLDisplay - - - - - - - - the native handle for the display - - - - - a #GstGLDisplay - - - - - - - - whether @context was successfully added. %FALSE may be returned -if there already exists another context for @context's active thread. - -Must be called with the object lock held. - - - - - a #GstGLDisplay - - - - a #GstGLContext - - - - - - It requires the display's object lock to be held. - - - whether a new context could be created. - - - - - a #GstGLDisplay - - - - other #GstGLContext to share resources with. - - - - resulting #GstGLContext - - - - - - - - a new #GstGLWindow for @display or %NULL. - - - - - a #GstGLDisplay - - - - - - limit the use of OpenGL to the requested @gl_api. This is intended to allow -application and elements to request a specific set of OpenGL API's based on -what they support. See gst_gl_context_get_gl_api() for the retrieving the -API supported by a #GstGLContext. - - - - - - - a #GstGLDisplay - - - - a #GstGLAPI to filter with - - - - - - Deprecated for gst_gl_display_retrieve_window(). - -Execute @compare_func over the list of windows stored by @display. The -first argument to @compare_func is the #GstGLWindow being checked and the -second argument is @data. - - - The first #GstGLWindow that causes a match - from @compare_func - - - - - a #GstGLDisplay - - - - some data to pass to @compare_func - - - - a comparison function to run - - - - - - see gst_gl_display_filter_gl_api() for what the returned value represents - - - the #GstGLAPI configured for @display - - - - - a #GstGLDisplay - - - - - - - - - - - - - - - - - - - the #GstGLContext current on @thread or %NULL - -Must be called with the object lock held. - - - - - a #GstGLDisplay - - - - a #GThread - - - - - - - - the native handle for the display - - - - - a #GstGLDisplay - - - - - - - - the #GstGLDisplayType of @display - - - - - a #GstGLDisplay - - - - - - Must be called with the object lock held. - - - - - - - a #GstGLDisplay - - - - the #GstGLContext to remove - - - - - - - - if @window could be removed from @display - - - - - a #GstGLDisplay - - - - a #GstGLWindow to remove - - - - - - Execute @compare_func over the list of windows stored by @display. The -first argument to @compare_func is the #GstGLWindow being checked and the -second argument is @data. - - - The first #GstGLWindow that causes a match - from @compare_func - - - - - a #GstGLDisplay - - - - some data to pass to @compare_func - - - - a comparison function to run - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Overrides the @GstGLContext creation mechanism. -It can be called in any thread and it is emitted with -display's object lock held. - - the new context. - - - - - other context to share resources with. - - - - - - - - - - - - - - - the native handle for the display - - - - - a #GstGLDisplay - - - - - - - - - - a new #GstGLWindow for @display or %NULL. - - - - - a #GstGLDisplay - - - - - - - - - - - - - - - - - no display type - - - X11 display - - - Wayland display - - - Cocoa display - - - Win32 display - - - Dispmanx display - - - EGL display - - - Vivante Framebuffer display - - - Mesa3D GBM display - - - EGLDevice display (Since: 1.18) - - - any display type - - - - #GstGLFilter helps to implement simple OpenGL filter elements taking a -single input and producing a single output with a #GstGLFramebuffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Calls filter_texture vfunc with correctly mapped #GstGLMemorys - - - whether the transformation succeeded - - - - - a #GstGLFilter - - - - an input buffer - - - - an output buffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Render a fullscreen quad using the current GL state. The only GL state this -modifies is the necessary vertex/index buffers and, if necessary, a -Vertex Array Object for drawing a fullscreen quad. Framebuffer state, -any shaders, viewport state, etc must be setup by the caller. - - - - - - - a #GstGLFilter - - - - - - Calls filter_texture vfunc with correctly mapped #GstGLMemorys - - - whether the transformation succeeded - - - - - a #GstGLFilter - - - - an input buffer - - - - an output buffer - - - - - - Transforms @input into @output using @func on through FBO. - - - the return value of @func - - - - - a #GstGLFilter - - - - the input texture - - - - the output texture - - - - the function to transform @input into @output. called with @data - - - - the data associated with @func - - - - - - Transforms @input into @output using @shader with a FBO. - -See also: gst_gl_filter_render_to_target() - - - - - - - a #GstGLFilter - - - - the input texture - - - - the output texture - - - - the shader to use. - - - - - - - - - the video info for input buffers - - - - the video info for output buffers - - - - The texture target of the input buffers (usually 2D) - - - - The texture target of the output buffers (usually 2D) - - - - the output #GstCaps - - - - #GstGLFramebuffer object used for transformations (only for subclass usage) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - whether the transformation succeeded - - - - - a #GstGLFilter - - - - an input buffer - - - - an output buffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - whether the render succeeded - - - - - the #GstGLFilter - - - - the input #GstGLMemory to render - - - - user data - - - - - - - Single component replicated across R, G, and B textures - components - - - Single component stored in the A texture component - - - Combination of #GST_GL_LUMINANCE and #GST_GL_ALPHA - - - Single component stored in the R texture component - - - Single 8-bit component stored in the R texture component - - - Two components stored in the R and G texture components - - - Two 8-bit components stored in the R and G texture components - - - Three components stored in the R, G, and B texture components - - - Three 8-bit components stored in the R, G, and B - texture components - - - Three components of bit depth 5, 6 and 5 stored in the R, G, - and B texture components respectively. - - - Three 16-bit components stored in the R, G, and B - texture components - - - Four components stored in the R, G, B, and A texture - components respectively. - - - Four 8-bit components stored in the R, G, B, and A texture - components respectively. - - - Four 16-bit components stored in the R, G, B, and A texture - components respectively. - - - A single 16-bit component for depth information. - - - A 24-bit component for depth information and - a 8-bit component for stencil informat. - - - - - Single 16-bit component stored in the R texture component - - - Two 16-bit components stored in the R and G texture components - - - - - the #GstGLFormat necessary for holding the data in @plane of @vinfo - - - - - a #GstGLContext - - - - a #GstVideoInfo - - - - the plane number in @vinfo - - - - - - - - Whether @format is supported by @context based on the OpenGL API, - version, or available OpenGL extension/s. - - - - - a #GstGLContext - - - - the #GstGLFormat to check is supported by @context - - - - - - Get the unsized format and type from @format for usage in glReadPixels, -glTex{Sub}Image*, glTexImage* and similar functions. - - - - - - - the sized internal #GstGLFormat - - - - location for the resulting unsized #GstGLFormat - - - - location for the resulting GL type - - - - - - - - the number of bytes the specified @format, @type combination takes -per pixel - - - - - the OpenGL format, `GL_RGBA`, `GL_LUMINANCE`, etc - - - - the OpenGL type, `GL_UNSIGNED_BYTE`, `GL_FLOAT`, etc - - - - - - - A #GstGLFramebuffer represents and holds an OpenGL framebuffer object with -it's associated attachments. - -A #GstGLFramebuffer can be created with gst_gl_framebuffer_new() or -gst_gl_framebuffer_new_with_default_depth() and bound with -gst_gl_framebuffer_bind(). Other resources can be bound with -gst_gl_framebuffer_attach() - -Note: OpenGL framebuffers are not shareable resources so cannot be used -between multiple OpenGL contexts. - - - - - a new #GstGLFramebuffer - - - - - a #GstGLContext - - - - - - - - a new #GstGLFramebuffer with a depth buffer of @width and @height - - - - - a #GstGLContext - - - - width for the depth buffer - - - - for the depth buffer - - - - - - attach @mem to @attachment_point - - - - - - - a #GstGLFramebuffer - - - - the OpenGL attachment point to bind @mem to - - - - the memory object to bind to @attachment_point - - - - - - Bind @fb into the current thread - - - - - - - a #GstGLFramebuffer - - - - - - Perform the steps necessary to have the output of a glDraw* command in -@func update the contents of @mem. - - - the result of executing @func - - - - - a #GstGLFramebuffer - - - - the #GstGLMemory to draw to - - - - the function to run - - - - data to pass to @func - - - - - - Retrieve the effective dimensions from the current attachments attached to -@fb. - - - - - - - a #GstGLFramebuffer - - - - output width - - - - output height - - - - - - - - the OpenGL id for @fb - - - - - a #GstGLFramebuffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Opaque #GstGLFramebufferClass struct - - - - - - - - - - - - callback definition for operating through a #GstGLFramebuffer object - - - - - - - user data - - - - - - - - - Structure containing function pointers to OpenGL functions. - -Each field is named exactly the same as the OpenGL function without the -`gl` prefix. - - - - GstGLMemory is a #GstGLBaseMemory subclass providing support for the mapping of -OpenGL textures. - -#GstGLMemory is created or wrapped through gst_gl_base_memory_alloc() -with #GstGLVideoAllocationParams. - -Data is uploaded or downloaded from the GPU as is necessary. - - - the parent #GstGLBaseMemory object - - - - the GL texture id for this memory - - - - the GL texture target for this memory - - - - the texture type - - - - the texture's #GstVideoInfo - - - - data alignment for system memory mapping - - - - data plane in @info - - - - GL shader scaling parameters for @valign and/or width/height - - - - - - - - - - - - - - - - - - - - Copies @gl_mem into the texture specfified by @tex_id. The format of @tex_id -is specified by @tex_format, @width and @height. - - - Whether the copy succeeded - - - - - a #GstGLMemory - - - - OpenGL texture id - - - - the #GstGLTextureTarget - - - - the #GstGLFormat - - - - width of @tex_id - - - - height of @tex_id - - - - - - Copies the texture in #GstGLMemory into the texture specified by @tex_id, -@out_target, @out_tex_format, @out_width and @out_height. - - - whether the copy succeeded. - - - - - the source #GstGLMemory - - - - the destination texture id - - - - the destination #GstGLTextureTarget - - - - the destination #GstGLFormat - - - - the destination width - - - - the destination height - - - - - - - - the #GstGLFormat of @gl_mem - - - - - a #GstGLMemory - - - - - - - - the texture height of @gl_mem - - - - - a #GstGLMemory - - - - - - - - the OpenGL texture handle of @gl_mem - - - - - a #GstGLMemory - - - - - - - - the #GstGLTextureTarget of @gl_mem - - - - - a #GstGLMemory - - - - - - - - the texture width of @gl_mem - - - - - a #GstGLMemory - - - - - - Initializes @mem with the required parameters. @info is assumed to have -already have been modified with gst_video_info_align(). - - - - - - - the #GstGLBaseMemory to initialize - - - - the #GstAllocator to initialize with - - - - the parent #GstMemory to initialize with - - - - the #GstGLContext to initialize with - - - - the #GstGLTextureTarget for this #GstGLMemory - - - - the #GstGLFormat for this #GstGLMemory - - - - the @GstAllocationParams to initialize with - - - - the #GstVideoInfo for this #GstGLMemory - - - - the plane number (starting from 0) for this #GstGLMemory - - - - optional #GstVideoAlignment parameters - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - Reads the texture in #GstGLMemory into @read_pointer if no buffer is bound -to `GL_PIXEL_PACK_BUFFER`. Otherwise @read_pointer is the byte offset into -the currently bound `GL_PIXEL_PACK_BUFFER` buffer to store the result of -glReadPixels. See the OpenGL specification for glReadPixels for more -details. - - - whether theread operation succeeded - - - - - a #GstGLMemory - - - - the data pointer to pass to glReadPixels - - - - - - See gst_gl_memory_read_pixels() for what @read_pointer signifies. - - - - - - - a #GstGLMemory - - - - the data pointer to pass to glTexSubImage - - - - - - Initializes the GL Base Texture allocator. It is safe to call this function -multiple times. This must be called before any other GstGLMemory operation. - - - - - - - - - whether the buffer was correctly setup - - - - - the @GstGLMemoryAllocator to allocate from - - - - a #GstBuffer to setup - - - - the #GstGLVideoAllocationParams to allocate with - - - - - a list of #GstGLFormat's to allocate with. - - - - - - - a list of wrapped data pointers - - - - - - the number of elements in @tex_formats and @wrapped_data - - - - - - - Opaque #GstGLMemoryAllocator struct - - - - - the default #GstGLMemoryAllocator supported by - @context - - - - - a #GstGLContext - - - - - - - - - - - - - - - - - - - - provide a custom map implementation - - - - provide a custom copy implementation - - - - provide a custom unmap implementation - - - - - - - - - - #GstGLMemoryPBO is created or wrapped through gst_gl_base_memory_alloc() -with #GstGLVideoAllocationParams. - -Data is uploaded or downloaded from the GPU as is necessary. - - - - - - - - - - - - - - Copies @gl_mem into the texture specfified by @tex_id. The format of @tex_id -is specified by @tex_format, @width and @height. - -If @respecify is %TRUE, then the copy is performed in terms of the texture -data. This is useful for splitting RGBA textures into RG or R textures or -vice versa. The requirement for this to succeed is that the backing texture -data must be the same size, i.e. say a RGBA8 texture is converted into a RG8 -texture, then the RG texture must have twice as many pixels available for -output as the RGBA texture. - -Otherwise, if @respecify is %FALSE, then the copy is performed per texel -using glCopyTexImage. See the OpenGL specification for details on the -mappings between texture formats. - - - Whether the copy succeeded - - - - - a #GstGLMemoryPBO - - - - the destination texture id - - - - the destination #GstGLTextureTarget - - - - the destination #GstGLFormat - - - - width of @tex_id - - - - height of @tex_id - - - - stride of the backing texture data - - - - whether to copy the data or copy per texel - - - - - - Transfer the texture data from the texture into the PBO if necessary. - - - - - - - a #GstGLMemoryPBO - - - - - - Transfer the texture data from the PBO into the texture if necessary. - - - - - - - a #GstGLMemoryPBO - - - - - - - - - - - - - Opaque #GstGLMemoryPBOAllocator struct - - - - - - - - - - - - Only contains private data - - - - - - - - - - - - Opaque #GstGLOverlayCompositor object - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - no platform - - - the EGL platform used primarily with the X11, wayland - and android window systems as well as on embedded Linux - - - the GLX platform used primarily with the X11 window system - - - the WGL platform used primarily on Windows - - - the CGL platform used primarily on OS X - - - the EAGL platform used primarily on iOS - - - any OpenGL platform - - - - - The #GstGLPlatform represented by @platform_s - - - - - a space separated string of OpenGL platformss - - - - - - - - A space separated string of the OpenGL platforms enabled in @platform - - - - - a #GstGLPlatform to stringify - - - - - - - A #GstGLQuery represents and holds an OpenGL query object. Various types of -queries can be run or counters retrieved. - - - - - - - - - - - - - - - - - - - - - - - - - - Record the result of a counter - - - - - - - a #GstGLQuery - - - - - - End counting the query - - - - - - - a #GstGLQuery - - - - - - Frees a #GstGLQuery - - - - - - - a #GstGLQuery - - - - - - - - - - - - a #GstGLQuery - - - - a #GstGLContext - - - - the #GstGLQueryType - - - - - - - - the result of the query - - - - - a #GstGLQuery - - - - - - Start counting the query - - - - - - - a #GstGLQuery - - - - - - Free any dynamically allocated resources - - - - - - - a #GstGLQuery - - - - - - Performs a GST_QUERY_CONTEXT query of type "gst.gl.local_context" on all -#GstPads in @element of @direction for the local OpenGL context used by -GStreamer elements. - - - whether @context_ptr contains a #GstGLContext - - - - - a #GstElement to query from - - - - the #GstPadDirection to query - - - - location containing the current and/or resulting - #GstGLContext - - - - - - Free with gst_gl_query_free() - - - a new #GstGLQuery - - - - - a #GstGLContext - - - - the #GstGLQueryType to create - - - - - - - - no query - - - query the time elapsed - - - query the current time - - - - GstGLRenderbuffer is a #GstGLBaseMemory subclass providing support for -OpenGL renderbuffers. - -#GstGLRenderbuffer is created or wrapped through gst_gl_base_memory_alloc() -with #GstGLRenderbufferAllocationParams. - - - - - - the GL texture id for this memory - - - - the texture type - - - - the width - - - - the height - - - - - - - - - - - - - - the #GstGLFormat of @gl_mem - - - - - a #GstGLRenderbuffer - - - - - - - - the configured height of @gl_mem - - - - - a #GstGLRenderbuffer - - - - - - - - the OpenGL renderbuffer handle of @gl_mem - - - - - a #GstGLRenderbuffer - - - - - - - - the configured width of @gl_mem - - - - - a #GstGLRenderbuffer - - - - - - Initializes the GL Base Texture allocator. It is safe to call this function -multiple times. This must be called before any other GstGLRenderbuffer operation. - - - - - - - - Allocation parameters - - - - - - the #GstGLFormat - - - - the width - - - - the height - - - - - - - - - - - a new #GstGLRenderbufferAllocationParams for allocating #GstGLRenderbuffer's - - - - - a #GstGLContext - - - - the #GstAllocationParams for sysmem mappings of the texture - - - - the #GstGLFormat for the created textures - - - - the width of the renderbuffer - - - - the height of the renderbuffer - - - - - - - - a new #GstGLRenderbufferAllocationParams for wrapping @gl_handle as a - renderbuffer - - - - - a #GstGLContext - - - - the #GstAllocationParams for @tex_id - - - - the #GstGLFormat for @tex_id - - - - the width of the renderbuffer - - - - the height of the renderbuffer - - - - the GL handle to wrap - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - - Opaque #GstGLRenderbufferAllocator struct - - - - - - - - - - - - The #GstGLRenderbufferAllocatorClass only contains private data - - - - - - - - - - - - Compilation stage that caused an error - - Compilation error occurred - - - Link error occurred - - - General program error occurred - - - - the quark used for GstGLSL in #GError's - - - - - - GLSL profiles - - no profile supported/available - - - OpenGL|ES profile - - - OpenGL core profile - - - OpenGL compatibility profile - - - any OpenGL/OpenGL|ES profile - - - - - the #GstGLSLProfile of @string or %GST_GLSL_PROFILE_NONE on error - - - - - a GLSL version string - - - - - - - - the name for @profile or %NULL on error - - - - - a #GstGLSLProfile - - - - - - - #GstGLSLStage holds and represents a single OpenGL shader stage. - - - - - a new #GstGLSLStage of the specified @type - - - - - a #GstGLContext - - - - the GL enum shader stage type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a new #GstGLSLStage of the specified @type - - - - - a #GstGLContext - - - - the GL enum shader stage type - - - - the #GstGLSLVersion - - - - the #GstGLSLProfile - - - - a shader string - - - - - - - - a new #GstGLSLStage of the specified @type - - - - - a #GstGLContext - - - - the GL enum shader stage type - - - - the #GstGLSLVersion - - - - the #GstGLSLProfile - - - - the number of strings in @str - - - - - an array of strings concatted together to produce a shader - - - - - - - - - - whether the compilation succeeded - - - - - a #GstGLSLStage - - - - - - - - The GL handle for this shader stage - - - - - a #GstGLSLStage - - - - - - - - The GLSL profile for the current shader stage - - - - - a #GstGLSLStage - - - - - - - - The GL shader type for this shader stage - - - - - a #GstGLSLStage - - - - - - - - The GLSL version for the current shader stage - - - - - a #GstGLSLStage - - - - - - Replaces the current shader string with @str. - - - - - - - a #GstGLSLStage - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - number of strings in @str - - - - a GLSL shader string - - - - - - - - - - - - - - - - - - - - - - - Opaque #GstGLSLStageClass struct - - - - - - - - - - - - - - - GLSL version list - - no version - - - version 100 (only valid for ES) - - - version 110 (only valid for compatibility desktop GL) - - - version 120 (only valid for compatibility desktop GL) - - - version 130 (only valid for compatibility desktop GL) - - - version 140 (only valid for compatibility desktop GL) - - - version 150 (valid for compatibility/core desktop GL) - - - version 300 (only valid for ES) - - - version 310 (only valid for ES) - - - version 320 (only valid for ES) - - - version 330 (valid for compatibility/core desktop GL) - - - version 400 (valid for compatibility/core desktop GL) - - - version 410 (valid for compatibility/core desktop GL) - - - version 420 (valid for compatibility/core desktop GL) - - - version 430 (valid for compatibility/core desktop GL) - - - version 440 (valid for compatibility/core desktop GL) - - - version 450 (valid for compatibility/core desktop GL) - - - - - the #GstGLSLVersion of @string or %GST_GLSL_VERSION_NONE on error - - - - - a GLSL version string - - - - - - Note: this function expects either a `#version` GLSL preprocesser directive -or a valid GLSL version and/or profile. - - - TRUE if a valid `#version` string was found, FALSE otherwise - - - - - a valid GLSL `#version` string - - - - resulting #GstGLSLVersion - - - - resulting #GstGLSLVersion - - - - - - - - the combined GLSL `#version` string for @version and @profile - - - - - a #GstGLSLVersion - - - - a #GstGLSLVersion - - - - - - - - the name of @version or %NULL on error - - - - - a #GstGLSLVersion - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Note: must be called in the GL thread - - - a new empty @shader - - - - - a #GstGLContext - - - - - - Note: must be called in the GL thread - - - a default @shader or %NULL on failure - - - - - a #GstGLContext - - - - - - Each stage will attempt to be compiled and attached to @shader. Then -the shader will be linked. On error, %NULL will be returned and @error will -contain the details of the error. - -Note: must be called in the GL thread - - - a new @shader with the specified stages. - - - - - a #GstGLContext - - - - a #GError - - - - a NULL terminated list of #GstGLSLStage's - - - - - - Each stage will attempt to be compiled and attached to @shader. On error, -%NULL will be returned and @error will contain the details of the error. - -Note: must be called in the GL thread - - - a new @shader with the specified stages. - - - - - a #GstGLContext - - - - a #GError - - - - a NULL terminated list of #GstGLSLStage's - - - - - - - - a passthrough shader string for copying an input external-oes - texture to the output - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - - - a passthrough shader string for copying an input texture to - the output - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - Generates a shader string that defines the precision of float types in -GLSL shaders. This is particularly needed for fragment shaders in a -GLSL ES context where there is no default precision specified. - -Practically, this will return the string 'precision mediump float' -or 'precision highp float' depending on if high precision floats are -determined to be supported. - - - a shader string defining the precision of float types based on - @context, @version and @profile - - - - - a #GstGLContext - - - - a #GstGLSLVersion - - - - a #GstGLSLProfile - - - - - - Attaches @stage to @shader. @stage must have been successfully compiled -with gst_glsl_stage_compile(). - -Note: must be called in the GL thread - - - whether @stage could be attached to @shader - - - - - a #GstGLShader - - - - a #GstGLSLStage to attach - - - - - - Attaches @stage to @shader. @stage must have been successfully compiled -with gst_glsl_stage_compile(). - -Note: must be called in the GL thread - - - whether @stage could be attached to @shader - - - - - a #GstGLShader - - - - a #GstGLSLStage to attach - - - - - - Bind attribute @name to the specified location @index using -`glBindAttributeLocation()`. - - - - - - - a #GstGLShader - - - - attribute index to set - - - - name of the attribute - - - - - - Bind attribute @name to the specified location @index using -`glBindFragDataLocation()`. - - - - - - - a #GstGLShader - - - - attribute index to set - - - - name of the attribute - - - - - - Compiles @stage and attaches it to @shader. - -Note: must be called in the GL thread - - - whether @stage could be compiled and attached to @shader - - - - - a #GstGLShader - - - - a #GstGLSLStage to attach - - - - - - Detaches @stage from @shader. @stage must have been successfully attached -to @shader with gst_gl_shader_attach() or gst_gl_shader_attach_unlocked(). - -Note: must be called in the GL thread - - - - - - - a #GstGLShader - - - - a #GstGLSLStage to attach - - - - - - Detaches @stage from @shader. @stage must have been successfully attached -to @shader with gst_gl_shader_attach() or gst_gl_shader_attach_unlocked(). - -Note: must be called in the GL thread - - - - - - - a #GstGLShader - - - - a #GstGLSLStage to attach - - - - - - - - the attribute index for @name in @shader or -1 on failure - - - - - a #GstGLShader - - - - name of the attribute - - - - - - - - the GL program handle for this shader - - - - - a #GstGLShader - - - - - - Note: must be called in the GL thread - - - whether @shader has been successfully linked - - - - - a #GstGLShader - - - - - - Links the current list of #GstGLSLStage's in @shader. - -Note: must be called in the GL thread - - - whether @shader could be linked together. - - - - - a #GstGLShader - - - - - - Releases the shader and stages. - -Note: must be called in the GL thread - - - - - - - a #GstGLShader - - - - - - Releases the shader and stages. - -Note: must be called in the GL thread - - - - - - - a #GstGLShader - - - - - - Perform `glUniform1f()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - value to set - - - - - - Perform `glUniform1fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform1i()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - value to set - - - - - - Perform `glUniform1iv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform2f()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - - - Perform `glUniform2fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform2i()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - - - Perform `glUniform2iv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform3f()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - third value to set - - - - - - Perform `glUniform3fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform3i()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - third value to set - - - - - - Perform `glUniform3iv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform4f()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - third value to set - - - - fourth value to set - - - - - - Perform `glUniform4fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniform4i()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - first value to set - - - - second value to set - - - - third value to set - - - - fourth value to set - - - - - - Perform `glUniform4iv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of values to set - - - - values to set - - - - - - - - Perform `glUniformMatrix2fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 2x2 matrices to set - - - - transpose the matrix - - - - matrix to set - - - - - - Perform `glUniformMatrix2x3fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 2x3 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix2x4fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 2x4 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix3fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 3x3 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix3x2fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 3x2 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix3x4fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 3x4 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix4fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 4x4 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix4x2fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 4x2 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Perform `glUniformMatrix4x3fv()` for @name on @shader - - - - - - - a #GstGLShader - - - - name of the uniform - - - - number of 4x3 matrices to set - - - - transpose the matrix - - - - values to set - - - - - - Mark's @shader as being used for the next GL draw command. - -Note: must be called in the GL thread and @shader must have been linked. - - - - - - - a #GstGLShader - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Output anaglyph type to generate when downmixing to mono - - Dubois optimised Green-Magenta anaglyph - - - Dubois optimised Red-Cyan anaglyph - - - Dubois optimised Amber-Blue anaglyph - - - - #GstGLSyncMeta provides the ability to synchronize the OpenGL command stream -with the CPU or with other OpenGL contexts. - - - the parent #GstMeta - - - - the #GstGLContext used to allocate the meta - - - - a custom data pointer for the implementation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Set a sync point to possibly wait on at a later time. - - - - - - - a #GstGLSyncMeta - - - - a #GstGLContext - - - - - - Insert a wait into @context's command stream ensuring all previous OpenGL -commands before @sync_meta have completed. - - - - - - - a #GstGLSyncMeta - - - - a #GstGLContext - - - - - - Perform a wait so that the sync point has passed from the CPU's perspective -What that means, is that all GL operations changing CPU-visible data before -the sync point are now visible. - - - - - - - a #GstGLSyncMeta - - - - a #GstGLContext - - - - - - - - - - - - - - no texture target - - - 2D texture target - - - rectangle texture target - - - external oes texture target - - - - - the #GstGLTextureTarget that's equiavalant to @target or - %GST_GL_TEXTURE_TARGET_NONE - - - - - an OpenGL texture binding target - - - - - - - - the #GstGLTextureTarget represented by @str or - %GST_GL_TEXTURE_TARGET_NONE - - - - - a string equivalent to one of the GST_GL_TEXTURE_TARGET_*_STR values - - - - - - - - a string representing the @GstBufferPoolOption specified by @target - - - - - a #GstGLTextureTarget - - - - - - - - the OpenGL value for binding the @target with glBindTexture() and - similar functions or 0 - - - - - a #GstGLTextureTarget - - - - - - - - the stringified version of @target or %NULL - - - - - a #GstGLTextureTarget - - - - - - - #GstGLUpload is an object that uploads data from system memory into GL textures. - -A #GstGLUpload can be created with gst_gl_upload_new() - - - - - a new #GstGLUpload object - - - - - a #GstGLContext - - - - - - - - - - - - - - - - - - a #GstGLUpload - - - - the input #GstCaps - - - - the output #GstCaps - - - - - - Uploads @buffer using the transformation specified by -gst_gl_upload_set_caps() creating a new #GstBuffer in @outbuf_ptr. - - - whether the upload was successful - - - - - a #GstGLUpload - - - - input #GstBuffer - - - - resulting #GstBuffer - - - - - - Adds the required allocation parameters to support uploading. - - - - - - - a #GstGLUpload - - - - a #GstQuery from a decide allocation - - - - the proposed allocation query - - - - - - Initializes @upload with the information required for upload. - - - whether @in_caps and @out_caps could be set on @upload - - - - - a #GstGLUpload - - - - input #GstCaps - - - - output #GstCaps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstGLUploadClass struct only contains private data - - - - - - - - - - - - - - - - No further processing required - - - An unspecified error occurred - - - The configuration is unsupported. - - - This element requires a reconfiguration. - - - private return value. - - - - - - the parent #GstGLAllocationParams structure - - - - the #GstVideoInfo to allocate - - - - the video plane index to allocate - - - - the #GstVideoAlignment to align the system representation to (may be %NULL for the default) - - - - the #GstGLTextureTarget to allocate - - - - the #GstGLFormat to allocate - - - - - - - - - - - a new #GstGLVideoAllocationParams for allocating #GstGLMemory's - - - - - a #GstGLContext - - - - the #GstAllocationParams for sysmem mappings of the texture - - - - the #GstVideoInfo for the texture - - - - the video plane of @v_info to allocate - - - - any #GstVideoAlignment applied to symem mappings of the texture - - - - the #GstGLTextureTarget for the created textures - - - - the #GstGLFormat for the created textures - - - - - - - - a new #GstGLVideoAllocationParams for wrapping @wrapped_data - - - - - a #GstGLContext - - - - the #GstAllocationParams for @wrapped_data - - - - the #GstVideoInfo for @wrapped_data - - - - the video plane @wrapped_data represents - - - - any #GstVideoAlignment applied to symem mappings of @wrapped_data - - - - the #GstGLTextureTarget for @wrapped_data - - - - the #GstGLFormat for @wrapped_data - - - - the data pointer to wrap - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - @gl_handle is defined by the specific OpenGL handle being wrapped -For #GstGLMemory and #GstGLMemoryPBO it is an OpenGL texture id. -Other memory types may define it to require a different type of parameter. - - - a new #GstGLVideoAllocationParams for wrapping @gl_handle - - - - - a #GstGLContext - - - - the #GstAllocationParams for @tex_id - - - - the #GstVideoInfo for @tex_id - - - - the video plane @tex_id represents - - - - any #GstVideoAlignment applied to symem mappings of @tex_id - - - - the #GstGLTextureTarget for @tex_id - - - - the #GstGLFormat for @tex_id - - - - the GL handle to wrap - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - - - a new #GstGLVideoAllocationParams for wrapping @tex_id - - - - - a #GstGLContext - - - - the #GstAllocationParams for @tex_id - - - - the #GstVideoInfo for @tex_id - - - - the video plane @tex_id represents - - - - any #GstVideoAlignment applied to symem mappings of @tex_id - - - - the #GstGLTextureTarget for @tex_id - - - - the #GstGLFormat for @tex_id - - - - the GL texture to wrap - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - Copy and set any dynamically allocated resources in @dest_vid. Intended -for subclass usage only to chain up at the end of a subclass copy function. - - - - - - - source #GstGLVideoAllocationParams to copy from - - - - destination #GstGLVideoAllocationParams to copy into - - - - - - Unset and free any dynamically allocated resources. Intended for subclass -usage only to chain up at the end of a subclass free function. - - - - - - - a #GstGLVideoAllocationParams - - - - - - Intended for subclass usage - - - initializes @params with the parameters specified - - - - - a #GstGLVideoAllocationParams to initialize - - - - the size of the struct in @params - - - - some allocation flags - - - - a copy function - - - - a free function - - - - a #GstGLContext - - - - the #GstAllocationParams for @wrapped_data - - - - the #GstVideoInfo for @wrapped_data - - - - the video plane @wrapped_data represents - - - - any #GstVideoAlignment applied to symem mappings of @wrapped_data - - - - the #GstGLTextureTarget - - - - the #GstGLFormat - - - - the optional data pointer to wrap - - - - the optional OpenGL handle to wrap or 0 - - - - user data to call @notify with - - - - a #GDestroyNotify - - - - - - - Convert stereoscopic/multiview video using fragment shaders. - - - - - a new #GstGLViewConvert - - - - - Provides an implementation of #GstBaseTransformClass.fixate_caps() - - - the fixated #GstCaps - - - - - a #GstGLViewConvert - - - - a #GstPadDirection - - - - the #GstCaps of @direction - - - - the #GstCaps to fixate - - - - - - Retrieve the processed output buffer placing the output in @outbuf_ptr. - - - a #GstFlowReturn - - - - - a #GstGLViewConvert - - - - a #GstBuffer - - - - - - Converts the data contained by @inbuf using the formats specified by the -#GstCaps passed to gst_gl_view_convert_set_caps() - - - a converted #GstBuffer or %NULL - - - - - a #GstGLViewConvert - - - - the #GstGLMemory filled #GstBuffer to convert - - - - - - Reset @viewconvert to the default state. Further operation will require -setting the caps with gst_gl_view_convert_set_caps(). - - - - - - - a #GstGLViewConvert - - - - - - Initializes @viewconvert with the information required for conversion. - - - - - - - a #GstGLViewConvert - - - - input #GstCaps - - - - output #GstCaps - - - - - - Set @context on @viewconvert - - - - - - - a #GstGLViewConvert - - - - the #GstGLContext to set - - - - - - Submit @input to be processed by @viewconvert - - - a #GstFlowReturn - - - - - a #GstGLViewConvert - - - - true if we have a discontinuity - - - - a #GstBuffer - - - - - - Provides an implementation of #GstBaseTransformClass.transform_caps() - - - the converted #GstCaps - - - - - a #GstGLViewConvert - - - - a #GstPadDirection - - - - the #GstCaps to transform - - - - a set of filter #GstCaps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Opaque #GstGLViewConvertClass struct - - - - - - - - - - - - - - - GstGLWindow represents a window that elements can render into. A window can -either be a user visible window (onscreen) or hidden (offscreen). - - - - - a new #GstGLWindow using @display's connection - - - - - a #GstGLDisplay - - - - - - - - - - - - - - - - - Checks if @window controls the GL viewport. - - - %TRUE if @window controls the GL viewport, otherwise %FALSE - - - - - a #GstGLWindow - - - - - - Redraw the window contents. Implementations should invoke the draw callback. - - - - - - - a #GstGLWindow - - - - - - - - the windowing system display handle for this @window - - - - - a #GstGLWindow - - - - - - - - the window handle we are currently rendering into - - - - - a #GstGLWindow - - - - - - Tell a @window that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window systems -events are not propagated in the window hierarchy if a client is listening -for them. This method allows you to disable events handling completely -from the @window. - - - - - - - a #GstGLWindow - - - - a #gboolean indicating if events should be handled or not. - - - - - - Query whether @window has output surface or not - - - %TRUE if @window has useable output surface - - - - - a #GstGLWindow - - - - - - - - - - - - - - - - - Queue resizing of @window. - - - - - - - a #GstGLWindow - - - - - - Quit the runloop's execution. - - - - - - - a #GstGLWindow - - - - - - Start the execution of the runloop. - - - - - - - a #GstGLWindow - - - - - - Invoke @callback with data on the window thread. @callback is guaranteed to -have executed when this function returns. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - - - Invoke @callback with @data on the window thread. The callback may not -have been executed when this function returns. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed anymore - - - - - - Set the preferred width and height of the window. Implementations are free -to ignore this information. - - - - - - - a #GstGLWindow - - - - new preferred width - - - - new preferred height - - - - - - Tell a @window that it should render into a specific region of the window -according to the #GstVideoOverlay interface. - - - whether the specified region could be set - - - - - a #GstGLWindow - - - - x position - - - - y position - - - - width - - - - height - - - - - - Sets the window that this @window should render into. Some implementations -require this to be called with a valid handle before drawing can commence. - - - - - - - a #GstGLWindow - - - - handle to the window - - - - - - Present the window to the screen. - - - - - - - a #GstGLWindow - - - - - - Checks if @window controls the GL viewport. - - - %TRUE if @window controls the GL viewport, otherwise %FALSE - - - - - a #GstGLWindow - - - - - - Redraw the window contents. Implementations should invoke the draw callback. - - - - - - - a #GstGLWindow - - - - - - - - the #GstGLContext associated with this @window - - - - - a #GstGLWindow - - - - - - - - the windowing system display handle for this @window - - - - - a #GstGLWindow - - - - - - - - - - - - a #GstGLWindow - - - - resulting surface width - - - - resulting surface height - - - - - - - - the window handle we are currently rendering into - - - - - a #GstGLWindow - - - - - - Tell a @window that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window systems -events are not propagated in the window hierarchy if a client is listening -for them. This method allows you to disable events handling completely -from the @window. - - - - - - - a #GstGLWindow - - - - a #gboolean indicating if events should be handled or not. - - - - - - Query whether @window has output surface or not - - - %TRUE if @window has useable output surface - - - - - a #GstGLWindow - - - - - - Queue resizing of @window. - - - - - - - a #GstGLWindow - - - - - - Quit the runloop's execution. - - - - - - - a #GstGLWindow - - - - - - Resize @window to the given @width and @height. - - - - - - - a #GstGLWindow - - - - new width - - - - new height - - - - - - Start the execution of the runloop. - - - - - - - a #GstGLWindow - - - - - - - - - - - - - - - - - - - - - - - Invoke @callback with data on the window thread. @callback is guaranteed to -have executed when this function returns. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - - - Invoke @callback with @data on the window thread. The callback may not -have been executed when this function returns. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed anymore - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Notify a @window about a scroll event. A scroll signal holding the event -coordinates will be emitted. - - - - - - - a #GstGLWindow - - - - x position of the mouse cursor - - - - y position of the mouse cursor - - - - the x offset of the scroll event - - - - the y offset of the scroll event - - - - - - Sets the callback called when the window is about to close. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed any more - - - - - - Sets the draw callback called every time gst_gl_window_draw() is called - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed any more - - - - - - Set the preferred width and height of the window. Implementations are free -to ignore this information. - - - - - - - a #GstGLWindow - - - - new preferred width - - - - new preferred height - - - - - - Tell a @window that it should render into a specific region of the window -according to the #GstVideoOverlay interface. - - - whether the specified region could be set - - - - - a #GstGLWindow - - - - x position - - - - y position - - - - width - - - - height - - - - - - Sets the resize callback called every time a resize of the window occurs. - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed any more - - - - - - Sets the window that this @window should render into. Some implementations -require this to be called with a valid handle before drawing can commence. - - - - - - - a #GstGLWindow - - - - handle to the window - - - - - - Present the window to the screen. - - - - - - - a #GstGLWindow - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Will be emitted when a key event is received by the GstGLwindow. - - - - - - the name of the event - - - - the id of the key pressed - - - - - - Will be emitted when a mouse event is received by the GstGLwindow. - - - - - - the name of the event - - - - the id of the button - - - - the x coordinate of the mouse event - - - - the y coordinate of the mouse event - - - - - - Will be emitted when a mouse scroll event is received by the GstGLwindow. - - - - - - the x coordinate of the mouse event - - - - the y coordinate of the mouse event - - - - the x offset of the scroll event - - - - the y offset of the scroll event - - - - - - - - - - - - - - - - - - - - Parent class - - - - - - - the windowing system display handle for this @window - - - - - a #GstGLWindow - - - - - - - - - - - - - - a #GstGLWindow - - - - handle to the window - - - - - - - - - - the window handle we are currently rendering into - - - - - a #GstGLWindow - - - - - - - - - - - - - - a #GstGLWindow - - - - - - - - - - - - - - a #GstGLWindow - - - - - - - - - - - - - - a #GstGLWindow - - - - - - - - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - - - - - - - - - - - a #GstGLWindow - - - - function to invoke - - - - data to invoke @callback with - - - - called when @data is not needed anymore - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstGLWindow - - - - a #gboolean indicating if events should be handled or not. - - - - - - - - - - - - - - a #GstGLWindow - - - - new preferred width - - - - new preferred height - - - - - - - - - - - - - - a #GstGLWindow - - - - - - - - - - whether the specified region could be set - - - - - a #GstGLWindow - - - - x position - - - - y position - - - - width - - - - height - - - - - - - - - - - - - - a #GstGLWindow - - - - - - - - - - %TRUE if @window controls the GL viewport, otherwise %FALSE - - - - - a #GstGLWindow - - - - - - - - - - %TRUE if @window has useable output surface - - - - - a #GstGLWindow - - - - - - - - - - - - - - failed for a unspecified reason - - - the implementation is too old - - - no such resource was found - - - - the quark used for #GstGLWindow in #GError's - - - - - - - - - - - - - - - - - - - - - - - - - - GL Allocation flag indicating that the implementation should allocate the -necessary resources. - - - - - GL allocation flag indicating the allocation of a GL buffer. - - - - - Values >= than #GST_GL_ALLOCATION_PARAMS_ALLOC_FLAG_USER can be used for -user-defined purposes. - - - - - GL allocation flag indicating the allocation of 2D video frames - - - - - GL Allocation flag for using the provided GPU handle as storage. - - - - - GL Allocation flag for using the provided system memory data as storage. - - - - - The name for %GST_GL_API_GLES1 used in various places - - - - - The name for %GST_GL_API_GLES2 used in various places - - - - - The name for %GST_GL_API_OPENGL3 used in various places - - - - - The name for %GST_GL_API_OPENGL used in various places - - - - - Stores a debug message in @ad for later output - - - - the #GstGLAsyncDebug to store the message in - - - the #GstDebugCategory to output the message in - - - the #GstDebugLevel - - - a #GObject to associate with the debug message - - - a printf style format string - - - the list of arguments for @format - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the GL buffer allocator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the GL buffer allocator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The currently supported formats that can be converted - - - - - The currently supported #GstCaps that can be converted - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name used in #GstContext queries for requesting a #GstGLDisplay - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the GL memory allocator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the GL Memory PBO allocator - - - - - - - - - List of video formats that are supported by #GstGLMemory - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The name of the GL renderbuffer allocator - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - String used for %GST_GL_TEXTURE_TARGET_2D in things like caps values - - - - - String used for %GST_GL_TEXTURE_TARGET_EXTERNAL_OES in things like caps values - - - - - String used for %GST_GL_TEXTURE_TARGET_RECTANGLE in things like caps values - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Cast to the current function type for generic window callbacks - - - - the function to cast - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Cast to the current function type for window resize callbacks - - - - the function to cast - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Flag indicating that we should map the GL object instead of to system memory. - -Combining #GST_MAP_GL with #GST_MAP_WRITE has the same semantics as though -you are writing to OpenGL. Conversely, combining #GST_MAP_GL with -#GST_MAP_READ has the same semantics as though you are reading from OpenGL. - - - - - - - the #GstGLSyncMeta added to #GstBuffer - - - - - a #GstGLContext - - - - a #GstBuffer - - - - - - - - the #GstGLSyncMeta added to #GstBuffer - - - - - a #GstGLContext - - - - a #GstBuffer - - - - sync data to hold - - - - - - - - - - - - - - - the currently set #GstGLAllocationParams or %NULL - - - - - a buffer pool config - - - - - - Sets @params on @config - - - - - - - a buffer pool config - - - - a #GstGLAllocationParams - - - - - - - - Whether @display was in @context - - - - - a #GstContext - - - - resulting #GstGLDisplay - - - - - - Sets @display on @context - - - - - - - a #GstContext - - - - resulting #GstGLDisplay - - - - - - - - The #GstGLAPI represented by @api_s - - - - - a space separated string of OpenGL apis - - - - - - - - A space separated string of the OpenGL api's enabled in @api - - - - - a #GstGLAPI to stringify - - - - - - Free with gst_gl_async_debug_free() - - - a new #GstGLAsyncDebug - - - - - - - a new #GstGLBaseMemory from @allocator with the requested @params. - - - - - a #GstGLBaseMemoryAllocator - - - - the #GstGLAllocationParams to allocate the memory with - - - - - - - the quark used for #GstGLBaseMemory in #GError's - - - - - Initializes the GL Base Memory allocator. It is safe to call this function -multiple times. This must be called before any other GstGLBaseMemory operation. - - - - - - - Initializes the GL Buffer allocator. It is safe to call this function -multiple times. This must be called before any other #GstGLBuffer operation. - - - - - - - - - whether @name is in the space separated list of @ext - - - - - the extension to search for - - - - the list of possible extensions - - - - - - - the quark used for #GstGLContext in #GError's - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Perform the steps necessary for retrieving a #GstGLDisplay and (optionally) -an application provided #GstGLContext from the surrounding elements or from -the application using the #GstContext mechanism. - -If the contents of @display_ptr or @other_context_ptr are not %NULL, then no -#GstContext query is necessary for #GstGLDisplay or #GstGLContext retrieval -or is performed. - -This performs #GstContext queries (if necessary) for a winsys display -connection with %GST_GL_DISPLAY_CONTEXT_TYPE, "gst.x11.display.handle", and -"GstWaylandDisplayHandleContextType" stopping after the first successful -retrieval. - -This also performs a #GstContext query (if necessary) for an optional -application provided #GstGLContext using the name "gst.gl.app_context". -The returned #GstGLContext will be shared with a GStreamer created OpenGL context. - - - whether a #GstGLDisplay exists in @display_ptr - - - - - the #GstElement running the query - - - - the resulting #GstGLDisplay - - - - the resulting #GstGLContext - - - - - - - - the #GstGLFormat necessary for holding the data in @plane of @vinfo - - - - - a #GstGLContext - - - - a #GstVideoInfo - - - - the plane number in @vinfo - - - - - - - - Whether @format is supported by @context based on the OpenGL API, - version, or available OpenGL extension/s. - - - - - a #GstGLContext - - - - the #GstGLFormat to check is supported by @context - - - - - - Get the unsized format and type from @format for usage in glReadPixels, -glTex{Sub}Image*, glTexImage* and similar functions. - - - - - - - the sized internal #GstGLFormat - - - - location for the resulting unsized #GstGLFormat - - - - location for the resulting GL type - - - - - - - - the number of bytes the specified @format, @type combination takes -per pixel - - - - - the OpenGL format, `GL_RGBA`, `GL_LUMINANCE`, etc - - - - the OpenGL type, `GL_UNSIGNED_BYTE`, `GL_FLOAT`, etc - - - - - - Retrieve the size in bytes of a video plane of data with a certain alignment - - - - - - - a #GstVideoInfo - - - - a #GstVideoAlignment or %NULL - - - - plane number in @info to retrieve the data size of - - - - - - - - difference between the supposed start of the plane from the @info - and where the data from the previous plane ends. - - - - - a #GstVideoInfo - - - - a #GstVideoAlignment or %NULL - - - - plane number in @info to retrieve the data size of - - - - - - - - Whether the @query was successfully responded to from the passed - @display, @context, and @other_context. - - - - - a #GstElement - - - - a #GstQuery of type %GST_QUERY_CONTEXT - - - - a #GstGLDisplay - - - - a #GstGLContext - - - - application provided #GstGLContext - - - - - - Helper function for implementing #GstElementClass.set_context() in -OpenGL capable elements. - -Retrieve's the #GstGLDisplay or #GstGLContext in @context and places the -result in @display or @other_context respectively. - - - whether the @display or @other_context could be set successfully - - - - - a #GstElement - - - - a #GstContext - - - - location of a #GstGLDisplay - - - - location of a #GstGLContext - - - - - - Inserts a marker into a GL debug stream. Requires the 'gldebugmarker' -debug category to be at least %GST_LEVEL_FIXME. - - - - - - - a #GstGLContext - - - - a printf-style format string - - - - arguments form @format - - - - - - Initializes the GL Base Texture allocator. It is safe to call this function -multiple times. This must be called before any other GstGLMemory operation. - - - - - - - - - - - - - - - whether the buffer was correctly setup - - - - - the @GstGLMemoryAllocator to allocate from - - - - a #GstBuffer to setup - - - - the #GstGLVideoAllocationParams to allocate with - - - - - a list of #GstGLFormat's to allocate with. - - - - - - - a list of wrapped data pointers - - - - - - the number of elements in @tex_formats and @wrapped_data - - - - - - - - The #GstGLPlatform represented by @platform_s - - - - - a space separated string of OpenGL platformss - - - - - - - - A space separated string of the OpenGL platforms enabled in @platform - - - - - a #GstGLPlatform to stringify - - - - - - - - - - - - - - - - - - - - - - - Performs a GST_QUERY_CONTEXT query of type "gst.gl.local_context" on all -#GstPads in @element of @direction for the local OpenGL context used by -GStreamer elements. - - - whether @context_ptr contains a #GstGLContext - - - - - a #GstElement to query from - - - - the #GstPadDirection to query - - - - location containing the current and/or resulting - #GstGLContext - - - - - - Free with gst_gl_query_free() - - - a new #GstGLQuery - - - - - a #GstGLContext - - - - the #GstGLQueryType to create - - - - - - - - - - - - - - - - - - - - - - - Initializes the GL Base Texture allocator. It is safe to call this function -multiple times. This must be called before any other GstGLRenderbuffer operation. - - - - - - - - - the sized internal format specified by @format and @type that can - be used in @context - - - - - a #GstGLContext - - - - an OpenGL format, `GL_RGBA`, `GL_LUMINANCE`, etc - - - - an OpenGL type, `GL_UNSIGNED_BYTE`, `GL_FLOAT`, etc - - - - - - - - - - - - - - - - - - - - - - - - - - the #GstGLTextureTarget that's equiavalant to @target or - %GST_GL_TEXTURE_TARGET_NONE - - - - - an OpenGL texture binding target - - - - - - - - the #GstGLTextureTarget represented by @str or - %GST_GL_TEXTURE_TARGET_NONE - - - - - a string equivalent to one of the GST_GL_TEXTURE_TARGET_*_STR values - - - - - - - - a string representing the @GstBufferPoolOption specified by @target - - - - - a #GstGLTextureTarget - - - - - - - - the OpenGL value for binding the @target with glBindTexture() and - similar functions or 0 - - - - - a #GstGLTextureTarget - - - - - - - - the stringified version of @target or %NULL - - - - - a #GstGLTextureTarget - - - - - - See gst_gl_value_set_texture_target_from_mask() for what entails a mask - - - the mask of #GstGLTextureTarget's in @value - - - - - an initialized #GValue of type G_TYPE_STRING - - - - - - - - whether the @target could be set on @value - - - - - an initialized #GValue of type G_TYPE_STRING - - - - a #GstGLTextureTarget's - - - - - - A mask is a bitwise OR of (1 << target) where target is a valid -#GstGLTextureTarget - - - whether the @target_mask could be set on @value - - - - - an uninitialized #GValue - - - - a bitwise mask of #GstGLTextureTarget's - - - - - - - - The minimum supported #GstGLSLVersion available for @gl_api, @maj and @min - - - - - the #GstGLAPI - - - - the major GL version - - - - the minor GL version - - - - - - - the quark used for #GstGLWindow in #GError's - - - - - - the quark used for GstGLSL in #GError's - - - - - - - the #GstGLSLProfile of @string or %GST_GLSL_PROFILE_NONE on error - - - - - a GLSL version string - - - - - - - - the name for @profile or %NULL on error - - - - - a #GstGLSLProfile - - - - - - Note: this function first searches the first 1 kilobytes for a `#version` -preprocessor directive and then executes gst_glsl_version_profile_from_string(). - - - TRUE if a valid `#version` string was found, FALSE otherwise - - - - - string to search for a valid `#version` string - - - - resulting #GstGLSLVersion - - - - resulting #GstGLSLProfile - - - - - - - - the #GstGLSLVersion of @string or %GST_GLSL_VERSION_NONE on error - - - - - a GLSL version string - - - - - - Note: this function expects either a `#version` GLSL preprocesser directive -or a valid GLSL version and/or profile. - - - TRUE if a valid `#version` string was found, FALSE otherwise - - - - - a valid GLSL `#version` string - - - - resulting #GstGLSLVersion - - - - resulting #GstGLSLVersion - - - - - - - - the combined GLSL `#version` string for @version and @profile - - - - - a #GstGLSLVersion - - - - a #GstGLSLVersion - - - - - - - - the name of @version or %NULL on error - - - - - a #GstGLSLVersion - - - - - - - - whether the memory at @mem is a #GstGLBaseMemory - - - - - a #GstMemory - - - - - - - - whether the memory at @mem is a #GstGLBuffer - - - - - a #GstMemory - - - - - - - - whether the memory at @mem is a #GstGLMemory - - - - - a #GstMemory - - - - - - - - whether the memory at @mem is a #GstGLMemoryPBO - - - - - a #GstMemory - - - - - - - - whether the memory at @mem is a #GstGLRenderbuffer - - - - - a #GstMemory - - - - - - - - - - the contents of a #GstGLDisplayEGL are private and should only be accessed -through the provided API - - - Create a new #GstGLDisplayEGL using the default EGL_DEFAULT_DISPLAY. - - - a new #GstGLDisplayEGL or %NULL - - - - - - - - - - - - - - - - Creates a EGL display connection from a native Display. - -This function will return the same value for multiple calls with the same -@display. - - - a new #GstGLDisplayEGL - - - - - an existing #GstGLDisplay - - - - - - Attempts to create a new `EGLDisplay` from @display. If @type is -%GST_GL_DISPLAY_TYPE_ANY, then @display must be 0. @type must not be -%GST_GL_DISPLAY_TYPE_NONE. - - - A `EGLDisplay` or `EGL_NO_DISPLAY` - - - - - a #GstGLDisplayType - - - - pointer to a display (or 0) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the contents of a #GstGLDisplayWayland are private and should only be accessed -through the provided API - - - Create a new #GstGLDisplayWayland from the wayland display name. See `wl_display_connect`() -for details on what is a valid name. - - - a new #GstGLDisplayWayland or %NULL - - - - - a display name - - - - - - Creates a new display connection from a wl_display Display. - - - a new #GstGLDisplayWayland - - - - - an existing, wayland display - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the contents of a #GstGLDisplayX11 are private and should only be accessed -through the provided API - - - Create a new #GstGLDisplayX11 from the x11 display name. See `XOpenDisplay`() -for details on what is a valid name. - - - a new #GstGLDisplayX11 or %NULL - - - - - a display name - - - - - - Creates a new display connection from a X11 Display. - - - a new #GstGLDisplayX11 - - - - - an existing, x11 display - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/gir-files/GstMpegts-1.0.gir b/gir-files/GstMpegts-1.0.gir deleted file mode 100644 index 5e84fbc6d..000000000 --- a/gir-files/GstMpegts-1.0.gir +++ /dev/null @@ -1,4711 +0,0 @@ - - - - - - - - - These values correspond to the registered descriptor type from -the various ATSC specifications. - -Consult the relevant specifications for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Event Information Table (ATSC) - - - The source id - - - - The protocol version - - - - Events - - - - - - - An ATSC EIT Event - - - The event id - - - - The start time - - - - The etm location - - - - The length in seconds - - - - the titles - - - - - - descriptors - - - - - - - Extended Text Table (ATSC) - - - - - - The protocol version - - - - The etm id - - - - List of texts - - - - - - - Master Guide Table (A65) - - - The protocol version - - - - The numbers of subtables - - - - the tables - - - - - - descriptors - - - - - - - - - - - - - Source from a @GstMpegtsAtscMGT - - - #GstMpegtsAtscMGTTableType - - - - The packet ID - - - - The version number - - - - - - - descriptors - - - - - - - - - - - - - - - - - - - - The ISO639 language code - - - - - - - - - - - - Region Rating Table (A65) - - - The protocol version - - - - the names - - - - - - the number of dimensions defined for this rating table - - - - A set of dimensions - - - - - - descriptors - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the abbreviated ratings - - - - - - the ratings - - - - - - - - - - - - - System Time Table (A65) - - - The protocol version - - - - The system time - - - - The GPS to UTC offset - - - - - - - The day of month - - - - The hour - - - - descriptors - - - - - - The UTC date and time - - - - - - - - - - - - - - - - - - - - - - A string segment - - - The compression type - - - - The mode - - - - The size of compressed data - - - - The compressed data - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Represents both: - Terrestrial Virtual Channel Table (A65) - Cable Virtual Channel Table (A65) - - - The transport stream - - - - The protocol version - - - - sources - - - - - - descriptors - - - - - - - Source from a @GstMpegtsAtscVCT, can be used both for TVCT and CVCT tables - - - The short name of a source - - - - The major channel number - - - - The minor channel number - - - - The modulation mode - - - - The carrier frequency - - - - The transport stream ID - - - - The program number (see #GstMpegtsPatProgram) - - - - The ETM location - - - - is access controlled - - - - is hidden - - - - is path select, CVCT only - - - - is out of band, CVCT only - - - - is hide guide - - - - The service type - - - - The source id - - - - an array of #GstMpegtsDescriptor - - - - - - - DVB Bouquet Association Table (EN 300 468) - - - - - - - - - - - - - - - - - - - - - - - - - - - - Cable Delivery System Descriptor (EN 300 468 v.1.13.1) - - - the frequency in Hz (Hertz) - - - - the outer FEC scheme used - - - - Modulation scheme used - - - - Symbol rate (in symbols per second) - - - - inner FEC scheme used - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of #GstMpegtsDescriptor - -These values correspond to the registered descriptor type from -the various DVB specifications. - -Consult the relevant specifications for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of #GstMpegtsDescriptor - -These values correspond to the registered extended descriptor -type from the various DVB specifications. - -Consult the relevant specifications for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the transport id - - - - the original network id - - - - the service id - - - - the type which @linkage_data has - - - - - - - the length for @private_data_bytes - - - - additional data bytes - - - - - - - - - - - - - - - - - The #GstMpegtsDVBLinkageEvent or %NULL if an error happened - - - - - the #GstMpegtsDVBLinkageDescriptor - - - - - - - - an #GstMpegtsDVBLinkageExtendedEvent array or %NULL if an error happened - - - - - - - the #GstMpegtsDVBLinkageDescriptor - - - - - - - - The #GstMpegtsDVBLinkageMobileHandOver or %NULL if an error happened - - - - - the #GstMpegtsDVBLinkageDescriptor - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Linkage Type (EN 300 468 v.1.13.1) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the id of a service - - - - the type of a service - - - - - The type of service of a channel. - -As specified in Table 87 of ETSI EN 300 468 v1.13.1 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of teletext page. - -As specified in Table 100 of ETSI EN 300 468 v1.13.1 - - - - - - - - - - - - - - - - the data broadcast id - - - - the component tag - - - - - - - the selector byte field - - - - language of @text - - - - description of data broadcast - - - - - - - - - - - - - - - - These are the base descriptor types and methods. - -For more details, refer to the ITU H.222.0 or ISO/IEC 13818-1 specifications -and other specifications mentioned in the documentation. - - - the type of descriptor - - - - the extended type (if @descriptor_tag is 0x7f) - - - - the length of the descriptor content (excluding tag/length field) - - - - the full descriptor data (including tag, extension, length). The first -two bytes are the @tag and @length. - - - - - - - - - Frees @desc - - - - - - - The descriptor to free - - - - - - Extracts the Conditional Access information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_CA #GstMpegtsDescriptor - - - - the type of CA system used - - - - The PID containing ECM or EMM data - - - - The private data - - - - - - The size of @private_data in bytes - - - - - - Extracts the cable delivery system information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_CABLE_DELIVERY_SYSTEM #GstMpegtsDescriptor - - - - the #GstMpegtsCableDeliverySystemDescriptor to fill - - - - - - Extracts the bouquet name from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - - - - the bouquet name - - - - - - Extracts ca id's from @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_CA_IDENTIFIER #GstMpegtsDescriptor - - - - a list of ca identifier. -Edge entry identifies the CA system. Allocations of the value of this field -are found in http://www.dvbservices.com - - - - - - - - Extracts the DVB component information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_COMPONENT #GstMpegtsDescriptor - - - - the #GstMpegtsComponentDescriptor to fill - - - - - - Extracts the DVB content information from @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_CONTENT #GstMpegtsDescriptor - - - - #GstMpegtsContent - - - - - - - - Parses out the data broadcast from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_DATA_BROADCAST #GstMpegtsDescriptor - - - - #GstMpegtsDataBroadcastDescriptor - - - - - - Parses out the data broadcast id from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_DATA_BROADCAST_ID #GstMpegtsDescriptor - - - - the data broadcast id - - - - the selector bytes, if present - - - - - - the length of @id_selector_bytes - - - - - - Extracts the DVB extended event information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_EXTENDED_EVENT #GstMpegtsDescriptor - - - - the #GstMpegtsExtendedEventDescriptor to fill - - - - - - Parses out a list of frequencies from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_FREQUENCY_LIST #GstMpegtsDescriptor - - - - %FALSE in Hz, %TRUE in kHz - - - - a list of all frequencies in Hz/kHz -depending on @offset - - - - - - - - Extracts the DVB linkage information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_LINKAGE #GstMpegtsDescriptor - - - - the #GstMpegtsDVBLinkageDescriptor to fill - - - - - - Parses out the multilingual bouquet name from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_MULTILINGUAL_BOUQUET_NAME -#GstMpegtsDescriptor - - - - -a #GstMpegtsDvbMultilingualBouquetNameItem - - - - - - - - Parses out the multilingual component from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_MULTILINGUAL_COMPONENT -#GstMpegtsDescriptor - - - - the component tag - - - - -a #GstMpegtsDvbMultilingualComponentItem - - - - - - - - Parses out the multilingual network name from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_MULTILINGUAL_NETWORK_NAME -#GstMpegtsDescriptor - - - - -a #GstMpegtsDvbMultilingualNetworkNameItem - - - - - - - - Parses out the multilingual service name from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_MULTILINGUAL_SERVICE_NAME -#GstMpegtsDescriptor - - - - -a #GstMpegtsDvbMultilingualServiceNameItem - - - - - - - - Parses out the dvb network name from the @descriptor: - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_NETWORK_NAME #GstMpegtsDescriptor - - - - the extracted name - - - - - - Extracts the DVB parental rating information from @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_PARENTAL_RATING #GstMpegtsDescriptor - - - - -#GstMpegtsDVBParentalRatingItem - - - - - - - - Parses out the private data specifier from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_PRIVATE_DATA_SPECIFIER #GstMpegtsDescriptor - - - - the private data specifier id -registered by http://www.dvbservices.com/ - - - - additional data or NULL - - - - - - length of @private_data - - - - - - Parses out the scrambling mode from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SCRAMBLING #GstMpegtsDescriptor - - - - This 8-bit field identifies the selected -mode of the scrambling algorithm (#GstMpegtsDVBScramblingModeType). -The technical details of the scrambling algorithm are available only -to bona-fide users upon signature of a Non Disclosure Agreement (NDA) -administered by the DVB Common Scrambling Algorithm Custodian. - - - - - - Extracts the dvb service information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SERVICE #GstMpegtsDescriptor - - - - the service type - - - - the service name - - - - the provider name - - - - - - Parses out a list of services from the @descriptor: - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SERVICE_LIST #GstMpegtsDescriptor - - - - -the list of services - - - - - - - - Extracts the DVB short event information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SHORT_EVENT #GstMpegtsDescriptor - - - - the language code - - - - the event name - - - - the event text - - - - - - Extracts the component tag from @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_CONTENT #GstMpegtsDescriptor - - - - the component tag - - - - - - Parses out the stuffing bytes from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_STUFFING #GstMpegtsDescriptor - - - - the stuffing bytes - - - - - - Extracts the DVB subtitling informatio from specific table id in @descriptor. - -Note: Use #gst_tag_get_language_code if you want to get the the -ISO 639-1 language code from the returned ISO 639-2 one. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SUBTITLING #GstMpegtsDescriptor - - - - Table id of the entry to parse - - - - the language code - - - - the type of subtitling - - - - the composition page id - - - - the ancillary page id - - - - - - - - The number of entries in @descriptor - - - - - a %GST_MTS_DESC_DVB_SUBTITLING #GstMpegtsDescriptor - - - - - - Parses out the DVB-T2 delivery system from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_EXT_DVB_T2_DELIVERY_SYSTEM #GstMpegtsDescriptor - - - - #GstMpegtsT2DeliverySystemDescriptor - - - - - - Parses teletext number @idx in the @descriptor. The language is in ISO639 format. - - - FALSE on out-of-bounds and errors - - - - - a %GST_MTS_DESC_DVB_TELETEXT #GstMpegtsDescriptor - - - - The id of the teletext to get - - - - a null-terminated string - - - - #GstMpegtsDVBTeletextType - - - - - - - - - - - - Find the number of teletext entries in @descriptor - - - Number of teletext entries - - - - - a %GST_MTS_DESC_DVB_TELETEXT #GstMpegtsDescriptor - - - - - - Extracts the iso 639-2 language information from @descriptor. - -Note: Use #gst_tag_get_language_code if you want to get the the -ISO 639-1 language code from the returned ISO 639-2 one. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_ISO_639_LANGUAGE #GstMpegtsDescriptor - - - - the #GstMpegtsISO639LanguageDescriptor to fill - - - - - - Extracts the iso 639-2 language information from specific table id in @descriptor. - -Note: Use #gst_tag_get_language_code if you want to get the the -ISO 639-1 language code from the returned ISO 639-2 one. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_ISO_639_LANGUAGE #GstMpegtsDescriptor - - - - Table id of the language to parse - - - - 4-byte gchar array to hold the language code - - - - the #GstMpegtsIso639AudioType to set - - - - - - - - The number of languages in @descriptor - - - - - a %GST_MTS_DESC_ISO_639_LANGUAGE #GstMpegtsDescriptor - - - - - - Extracts the logical channels from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DTG_LOGICAL_CHANNEL #GstMpegtsDescriptor - - - - the #GstMpegtsLogicalChannelDescriptor to fill - - - - - - Extracts the satellite delivery system information from @descriptor. - - - %TRUE if parsing succeeded, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_SATELLITE_DELIVERY_SYSTEM #GstMpegtsDescriptor - - - - the #GstMpegtsSatelliteDeliverySystemDescriptor to fill - - - - - - Parses out the terrestrial delivery system from the @descriptor. - - - %TRUE if the parsing happened correctly, else %FALSE. - - - - - a %GST_MTS_DESC_DVB_TERRESTRIAL_DELIVERY_SYSTEM #GstMpegtsDescriptor - - - - #GstMpegtsTerrestrialDeliverySystemDescriptor - - - - - - Creates a #GstMpegtsDescriptor with custom @tag and @data - - - #GstMpegtsDescriptor - - - - - descriptor tag - - - - descriptor data (after tag and length field) - - - - - - length of @data - - - - - - Creates a #GstMpegtsDescriptor with custom @tag, @tag_extension and @data - - - #GstMpegtsDescriptor - - - - - descriptor tag - - - - descriptor tag extension - - - - descriptor data (after tag and length field) - - - - - - length of @data - - - - - - Creates a #GstMpegtsDescriptor to be a %GST_MTS_DESC_DVB_NETWORK_NAME, -with the network name @name. The data field of the #GstMpegtsDescriptor -will be allocated, and transferred to the caller. - - - the #GstMpegtsDescriptor or %NULL on fail - - - - - the network name to set - - - - - - Fills a #GstMpegtsDescriptor to be a %GST_MTS_DESC_DVB_SERVICE. -The data field of the #GstMpegtsDescriptor will be allocated, -and transferred to the caller. - - - the #GstMpegtsDescriptor or %NULL on fail - - - - - Service type defined as a #GstMpegtsDVBServiceType - - - - Name of the service - - - - Name of the service provider - - - - - - - - - - - - a string containing the ISO639 language - - - - subtitling type - - - - composition page id - - - - ancillary page id - - - - - - Creates a %GST_MTS_DESC_ISO_639_LANGUAGE #GstMpegtsDescriptor with -a single language - - - #GstMpegtsDescriptor, %NULL on failure - - - - - ISO-639-2 language 3-char code - - - - - - Creates a %GST_MTS_DESC_REGISTRATION #GstMpegtsDescriptor - - - #GstMpegtsDescriptor, %NULL on failure - - - - - a 4 character format identifier string - - - - pointer to optional additional info - - - - - - length of the optional @additional_info - - - - - - - The type of #GstMpegtsDescriptor - -These values correspond to the registered descriptor type from -the base MPEG-TS specifications (ITU H.222.0 | ISO/IEC 13818-1). - -Consult the relevant specifications for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a multilingual bouquet name entry - - - the ISO 639 language code - - - - the bouquet name - - - - - - - the ISO 639 language code - - - - the component description - - - - - a multilingual network name entry - - - the ISO 639 language code - - - - the network name - - - - - a multilingual service name entry - - - the ISO 639 language code - - - - the provider name - - - - the service name - - - - - Event Information Table (EN 300 468) - - - - - - - - - - - - - - - - - - - - - List of events - - - - - - - Event from a @GstMpegtsEIT - - - - - - - - - - - - - - - - - - List of descriptors - - - - - - - Extended Event Descriptor (EN 300 468 v.1.13.1) - - - - - - - - - NULL terminated language code. - - - - the #GstMpegtsExtendedEventItem - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - These values correspond to the registered descriptor type from -the various ISDB specifications. - -Consult the relevant specifications for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The type of #GstMpegtsDescriptor - -These values correspond to miscellaneous descriptor types that are -not yet identified from known specifications. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Network Information Table (ISO/IEC 13818-1 / EN 300 468) - - - Whether this NIT corresponds to the actual stream - - - - ID of the network that this NIT describes - - - - the global descriptors - - - - - - the streams - - - - - - Allocates and initializes a #GstMpegtsNIT. - - - A newly allocated #GstMpegtsNIT - - - - - - - - - - - - - - - - - - - Allocates and initializes a #GstMpegtsNITStream - - - A newly allocated #GstMpegtsNITStream - - - - - - Program Map Table (ISO/IEC 13818-1). - -The program_number is contained in the subtable_extension field of the -container #GstMpegtsSection. - - - PID of the stream containing PCR - - - - - - - array of #GstMpegtsDescriptor - - - - - - Array of #GstMpegtsPMTStream - - - - - - Allocates and initializes a new #GstMpegtsPMT. - - - #GstMpegtsPMT - - - - - - An individual stream definition. - - - the type of stream. See #GstMpegtsStreamType - - - - the PID of the stream - - - - the descriptors of the -stream - - - - - - Allocates and initializes a new #GstMpegtsPMTStream. - - - #GstMpegtsPMTStream - - - - - - - - - - - - - - - - - A program entry from a Program Association Table (ITU H.222.0, ISO/IEC 13818-1). - - - the program number - - - - the network of program map PID - - - - Allocates a new #GstMpegtsPatProgram. - - - A newly allocated #GstMpegtsPatProgram - - - - - - Running status of a service. - -Corresponds to table 6 of ETSI EN 300 468 (v1.13.0) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Allocates and initializes a #GstMpegtsSCTESIT. - - - A newly allocated #GstMpegtsSCTESIT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Allocates and initializes a #GstMpegtsSCTESpliceEvent. - - - A newly allocated #GstMpegtsSCTESpliceEvent - - - - - - Service Description Table (EN 300 468) - - - Network ID of the originating delivery system - - - - True if the table describes this transport stream - - - - ID of this transport stream - - - - List of services - - - - - - Allocates and initializes a #GstMpegtsSDT. - - - A newly allocated #GstMpegtsSDT - - - - - - - - The program number this table belongs to - - - - EIT schedule information is present in this transport stream - - - - EIT present/following information is present in this transport stream - - - - Status of this service - - - - True if one or more streams is controlled by a CA system - - - - List of descriptors - - - - - - Allocates and initializes a #GstMpegtsSDTService. - - - A newly allocated #GstMpegtsSDTService - - - - - - - - - - - - - - - - - - - - Satellite Delivery System Descriptor (EN 300 468 v.1.13.1) - - - the frequency in kHz (kiloHertz) - - - - the orbital position in degrees - - - - If %TRUE, the satellite is in the eastern part of the orbit, -else in the western part. - - - - The polarization of the transmitted signal - - - - Roll-off factor used in DVB-S2 - - - - modulation system, %TRUE if DVB-S2, else DVB-S - - - - Modulation scheme used - - - - Symbol rate (in symbols per second) - - - - inner FEC scheme used - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Type of mpeg-ts streams for SCTE - - - SCTE-27 Subtitling - - - SCTE-19 Isochronous data - - - SCTE-35 Splice Information Table - - - SCTE-07 Data Service or -Network Resource Table - - - Type B - DSM-CC Data Carousel -[IEC 13818-6]) - - - Enhanced Television Application -Signaling (OC-SP-ETV-AM1.0.1-120614) - - - SCTE-07 Synchronous data - - - SCTE-53 Asynchronous data - - - - For more details, refer to the ITU H.222.0 or ISO/IEC 13818-1 specifications -and other specifications mentioned in the documentation. - - - - - - The type of section - - - - The pid on which this section was found - - - - The table id of this section - - - - This meaning differs per section. See the documentation -of the parsed section type for the meaning of this field - - - - Version of the section. - - - - Applies to current/next stream or not - - - - Number of the section (if multiple) - - - - Number of the last expected section (if multiple) - - - - CRC - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a new #GstMpegtsSection from the provided @data. - -Note: Ensuring @data is big enough to contain the full section is the -responsibility of the caller. If it is not big enough, %NULL will be -returned. - -Note: it is the responsibility of the caller to ensure @data does point -to the beginning of the section. - - - A new #GstMpegtsSection if the data was valid, -else %NULL - - - - - the PID to which this section belongs - - - - a pointer to the beginning of the section (i.e. the first byte -should contain the table_id field). - - - - - - size of the @data argument. - - - - - - Returns the #GstMpegtsAtscVCT contained in the @section - - - The #GstMpegtsAtscVCT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_CVCT - - - - - - Returns the #GstMpegtsAtscEIT contained in the @section. - - - The #GstMpegtsAtscEIT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_EIT - - - - - - Returns the #GstMpegtsAtscETT contained in the @section. - - - The #GstMpegtsAtscETT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_ETT - - - - - - Returns the #GstMpegtsAtscMGT contained in the @section. - - - The #GstMpegtsAtscMGT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_MGT - - - - - - Returns the #GstMpegtsAtscRRT contained in the @section. - - - The #GstMpegtsAtscRRT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_RRT - - - - - - Returns the #GstMpegtsAtscSTT contained in the @section. - - - The #GstMpegtsAtscSTT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_STT - - - - - - Returns the #GstMpegtsAtscVCT contained in the @section - - - The #GstMpegtsAtscVCT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_ATSC_TVCT - - - - - - Returns the #GstMpegtsBAT contained in the @section. - - - The #GstMpegtsBAT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_BAT - - - - - - Returns the array of #GstMpegtsDescriptor contained in the Conditional -Access Table. - - - The -#GstMpegtsDescriptor contained in the section, or %NULL if an error -happened. Release with #g_array_unref when done. - - - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_CAT - - - - - - Gets the original unparsed section data. - - - The original unparsed section data. - - - - - a #GstMpegtsSection - - - - - - Returns the #GstMpegtsEIT contained in the @section. - - - The #GstMpegtsEIT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_EIT - - - - - - Returns the #GstMpegtsNIT contained in the @section. - - - The #GstMpegtsNIT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_NIT - - - - - - Parses a Program Association Table (ITU H.222.0, ISO/IEC 13818-1). - -Returns the array of #GstMpegtsPatProgram contained in the section. - -Note: The PAT "transport_id" field corresponds to the "subtable_extension" -field of the provided @section. - - - The -#GstMpegtsPatProgram contained in the section, or %NULL if an error -happened. Release with #g_ptr_array_unref when done. - - - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_PAT - - - - - - Returns the #GstMpegtsPMT contained in the @section. - - - The #GstMpegtsPMT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_PMT - - - - - - Returns the #GstMpegtsSCTESIT contained in the @section. - - - The #GstMpegtsSCTESIT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_SCTE_SIT - - - - - - Returns the #GstMpegtsSDT contained in the @section. - - - The #GstMpegtsSDT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_SDT - - - - - - Returns the #GstDateTime of the TDT - - - The #GstDateTime contained in the section, or %NULL -if an error happened. Release with #gst_date_time_unref when done. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_TDT - - - - - - Returns the #GstMpegtsTOT contained in the @section. - - - The #GstMpegtsTOT contained in the section, or %NULL if an error -happened. - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_TOT - - - - - - Returns the array of #GstMpegtsDescriptor contained in the section - - - The -#GstMpegtsDescriptor contained in the section, or %NULL if an error -happened. Release with #g_array_unref when done. - - - - - - - a #GstMpegtsSection of type %GST_MPEGTS_SECTION_TSDT - - - - - - If the data in @section has already been packetized, the data pointer is returned -immediately. Otherwise, the data field is allocated and populated. - - - pointer to section data, or %NULL on fail - - - - - the #GstMpegtsSection that holds the data - - - - #gsize to hold the size of the data - - - - - - Creates a custom #GstEvent with a @GstMpegtsSection. -The #GstEvent is sent to the @element #GstElement. - - - %TRUE if the event is sent - - - - - The #GstMpegtsSection to put in the event - - - - The #GstElement to send to section event to - - - - - - - - the #GstMpegtsSection - - - - - a #GstMpegtsAtscMGT to create the #GstMpegtsSection from - - - - - - - - - - - - - - - - - - - - - - - - - - - - Ownership of @nit is taken. The data in @nit is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsNIT to create the #GstMpegtsSection from - - - - - - Creates a PAT #GstMpegtsSection from the @programs array of #GstMpegtsPatPrograms - - - a #GstMpegtsSection - - - - - an array of #GstMpegtsPatProgram - - - - - - Transport stream ID of the PAT - - - - - - Creates a #GstMpegtsSection from @pmt that is bound to @pid - - - #GstMpegtsSection - - - - - a #GstMpegtsPMT to create a #GstMpegtsSection from - - - - The PID that the #GstMpegtsPMT belongs to - - - - - - Ownership of @sit is taken. The data in @sit is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsSCTESIT to create the #GstMpegtsSection from - - - - - - - - - Ownership of @sdt is taken. The data in @sdt is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsSDT to create the #GstMpegtsSection from - - - - - - - Values for a #GstMpegtsSection table_id. - -These are the registered ATSC table_id variants. - -see also: #GstMpegtsSectionTableID - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Values for a #GstMpegtsSection table_id. - -These are the registered DVB table_id variants. - -see also: #GstMpegtsSectionTableID - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Values for a #GstMpegtsSection table_id. - -These are the registered SCTE table_id variants. - -see also: #GstMpegtsSectionTableID - - - SCTE-18 Emergency Alert System - - - CL-SP-ETV-AM 1.0.1 EBIF message - - - - - CL-SP-ETV-AM 1.0.1 EBIF Int. Signaling Sect. - - - CL-SP-ETV-AM 1.0.1 DSMCC DII message - - - CL-SP-ETV-AM 1.0.1 DSMCC Data Download Block - - - SCTE-35 splice information is carried in a -section stream on a separate PID in the program’s Map Table (PMT) allowing -Splice Event notifications to remain associated with the program and pass -through multiplexers. - - - - Values for a #GstMpegtsSection table_id - -These are the registered ITU H.222.0 | ISO/IEC 13818-1 table_id variants. - -see also #GstMpegtsSectionATSCTableID, #GstMpegtsSectionDVBTableID, and -#GstMpegtsSectionSCTETableID - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Types of #GstMpegtsSection that the library handles. - - - Unknown section type - - - Program Association Table (ISO/IEC 13818-1) - - - Program Map Table (ISO/IEC 13818-1) - - - Conditional Access Table (ISO/IEC 13818-1) - - - Transport Stream Description Table (ISO/IEC 13818-1) - - - Event Information Table (EN 300 468) - - - Network Information Table (ISO/IEC 13818-1 / EN 300 468) - - - Bouquet Association Table ((EN 300 468) - - - Service Description Table (EN 300 468) - - - Time and Date Table (EN 300 468) - - - Time Offset Table (EN 300 468) - - - ATSC Terrestrial Virtual Channel Table (A65) - - - ATSC Cable Virtual Channel Table (A65) - - - ATSC Master Guide Table (A65) - - - ATSC Extended Text Table (A65) - - - ATSC Event Information Table (A65) - - - ATSC System Time Table (A65) - - - - - SCTE Splice Information Table (SCTE-35) - - - - Type of mpeg-ts stream type. - -These values correspond to the base standard registered types. Depending -on the variant of mpeg-ts being used (Bluray, ATSC, DVB, ...), other -types might also be used, but will not conflict with these. - -Corresponds to table 2-34 of ITU H.222.0 | ISO/IEC 13818-1 - - - ITU-T | ISO/IEC Reserved - - - ISO/IEC 11172-2 Video - - - Rec. ITU-T H.262 | ISO/IEC 13818-2 -Video or ISO/IEC 11172-2 constrained parameter video stream - - - ISO/IEC 11172-3 Audio - - - ISO/IEC 13818-3 Audio - - - private sections - - - PES packets containing private data - - - ISO/IEC 13522 MHEG - - - Annex A DSM-CC - - - Rec. ITU-T H.222.1 - - - ISO/IEC 13818-6 type A - - - ISO/IEC 13818-6 type B - - - ISO/IEC 13818-6 type C - - - ISO/IEC 13818-6 type D - - - auxiliary streams - - - ISO/IEC 13818-7 Audio with ADTS -transport syntax - - - ISO/IEC 14496-2 Visual - - - ISO/IEC 14496-3 Audio with the LATM -transport syntax as defined in ISO/IEC 14496-3 - - - ISO/IEC 14496-1 -SL-packetized stream or FlexMux stream carried in PES packets - - - ISO/IEC 14496-1 SL-packetized -stream or FlexMux stream carried in ISO/IEC 14496_sections - - - ISO/IEC 13818-6 Synchronized -Download Protocol - - - Metadata carried in PES packets - - - Metadata carried in metadata_sections - - - Metadata carried in ISO/IEC -13818-6 Data Carousel - - - Metadata carried in -ISO/IEC 13818-6 Object Carousel - - - Metadata carried in -ISO/IEC 13818-6 Synchronized Download Protocol - - - IPMP stream (defined in ISO/IEC 13818-11, -MPEG-2 IPMP) - - - AVC video stream conforming to one or -more profiles defined in Annex A of Rec. ITU-T H.264 | ISO/IEC 14496-10 or -AVC video sub-bitstream of SVC as defined in 2.1.78 or MVC base view -sub-bitstream, as defined in 2.1.85, or AVC video sub-bitstream of MVC, as -defined in 2.1.88 - - - ISO/IEC 14496-3 Audio, without -using any additional transport syntax, such as DST, ALS and SLS - - - ISO/IEC 14496-17 Text - - - Auxiliary video stream as defined in -ISO/IEC 23002-3 - - - SVC video sub-bitstream -of an AVC video stream conforming to one or more profiles defined in Annex G -of Rec. ITU-T H.264 | ISO/IEC 14496-10 - - - MVC video sub-bitstream -of an AVC video stream conforming to one or more profiles defined in Annex H -of Rec. ITU-T H.264 | ISO/IEC 14496-10 - - - Video stream conforming to one or more -profiles as defined in Rec. ITU-T T.800 | ISO/IEC 15444-1 - - - Additional view -Rec. ITU-T H.262 | ISO/IEC 13818-2 video stream for service-compatible -stereoscopic 3D services - - - Additional view -Rec. ITU-T H.264 | ISO/IEC 14496-10 video stream conforming to one or more -profiles defined in Annex A for service-compatible stereoscopic 3D services - - - - - IPMP stream - - - - - - id of the cell - - - - centre frequencies in Hz - - - - - - - - - - - - - - id of the sub cell - - - - centre frequency of the sub cell in Hz - - - - - describe DVB-T2 transmissions according to EN 302 755 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Time Offset Table (EN 300 468) - - - - - - List of descriptors - - - - - - - Terrestrial Delivery System Descriptor (EN 300 468 v.1.13.1) - - - the frequency in Hz (Hertz) - - - - the bandwidth in Hz (Hertz) - - - - %TRUE High Priority %FALSE Low Priority - - - - %TRUE no time slicing %FALSE time slicing - - - - %TRUE no mpe-fec is used %FALSE mpe-fec is use - - - - the constellation - - - - the hierarchy - - - - - - - - - - - - - - - - %TRUE more frequency are use, else not - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a #GstMpegtsDescriptor with custom @tag and @data - - - #GstMpegtsDescriptor - - - - - descriptor tag - - - - descriptor data (after tag and length field) - - - - - - length of @data - - - - - - Creates a #GstMpegtsDescriptor with custom @tag, @tag_extension and @data - - - #GstMpegtsDescriptor - - - - - descriptor tag - - - - descriptor tag extension - - - - descriptor data (after tag and length field) - - - - - - length of @data - - - - - - Creates a #GstMpegtsDescriptor to be a %GST_MTS_DESC_DVB_NETWORK_NAME, -with the network name @name. The data field of the #GstMpegtsDescriptor -will be allocated, and transferred to the caller. - - - the #GstMpegtsDescriptor or %NULL on fail - - - - - the network name to set - - - - - - Fills a #GstMpegtsDescriptor to be a %GST_MTS_DESC_DVB_SERVICE. -The data field of the #GstMpegtsDescriptor will be allocated, -and transferred to the caller. - - - the #GstMpegtsDescriptor or %NULL on fail - - - - - Service type defined as a #GstMpegtsDVBServiceType - - - - Name of the service - - - - Name of the service provider - - - - - - - - - - - - a string containing the ISO639 language - - - - subtitling type - - - - composition page id - - - - ancillary page id - - - - - - Creates a %GST_MTS_DESC_ISO_639_LANGUAGE #GstMpegtsDescriptor with -a single language - - - #GstMpegtsDescriptor, %NULL on failure - - - - - ISO-639-2 language 3-char code - - - - - - Creates a %GST_MTS_DESC_REGISTRATION #GstMpegtsDescriptor - - - #GstMpegtsDescriptor, %NULL on failure - - - - - a 4 character format identifier string - - - - pointer to optional additional info - - - - - - length of the optional @additional_info - - - - - - - - - - - - - - - - - Extracts the #GstMpegtsSection contained in the @event #GstEvent - - - The extracted #GstMpegtsSection - - - - - #GstEvent containing a #GstMpegtsSection - - - - - - Finds the first descriptor of type @tag in the array. - -Note: To look for descriptors that can be present more than once in an -array of descriptors, iterate the #GArray manually. - - - the first descriptor matching @tag, else %NULL. - - - - - an array -of #GstMpegtsDescriptor - - - - - - the tag to look for - - - - - - Initializes the MPEG-TS helper library. Must be called before any -usage. - - - - - - - Creates a new #GstMessage for a @GstMpegtsSection. - - - The new #GstMessage to be posted, or %NULL if the -section is not valid. - - - - - The creator of the message - - - - The #GstMpegtsSection to put in a message - - - - - - Returns the #GstMpegtsSection contained in a message. - - - the contained #GstMpegtsSection, or %NULL. - - - - - a #GstMessage - - - - - - Parses the descriptors present in @buffer and returns them as an -array. - -Note: The data provided in @buffer will not be copied. - - - an -array of the parsed descriptors or %NULL if there was an error. -Release with #g_array_unref when done with it. - - - - - - - descriptors to parse - - - - Size of @buffer - - - - - - Allocates a new #GPtrArray for #GstMpegtsPatProgram - - - A newly allocated #GPtrArray - - - - - - - Allocates and initializes a new INSERT command #GstMpegtsSCTESIT -setup to cancel the specified @event_id. - - - A newly allocated #GstMpegtsSCTESIT - - - - - The event ID to cancel. - - - - - - Allocates and initializes a NULL command #GstMpegtsSCTESIT. - - - A newly allocated #GstMpegtsSCTESIT - - - - - Allocates and initializes a new "Splice In" INSERT command -#GstMpegtsSCTESIT for the given @event_id and @splice_time. - -If the @splice_time is #G_MAXUINT64 then the event will be -immediate as opposed to for the target @splice_time. - - - A newly allocated #GstMpegtsSCTESIT - - - - - The event ID. - - - - The PCR time for the splice event - - - - - - Allocates and initializes a new "Splice Out" INSERT command -#GstMpegtsSCTESIT for the given @event_id, @splice_time and -duration. - -If the @splice_time is #G_MAXUINT64 then the event will be -immediate as opposed to for the target @splice_time. - -If the @duration is 0 it won't be specified in the event. - - - A newly allocated #GstMpegtsSCTESIT - - - - - The event ID. - - - - The PCR time for the splice event - - - - The optional duration. - - - - - - - - the #GstMpegtsSection - - - - - a #GstMpegtsAtscMGT to create the #GstMpegtsSection from - - - - - - - - - - - - - - - - - - - - - - - - - - - - Ownership of @nit is taken. The data in @nit is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsNIT to create the #GstMpegtsSection from - - - - - - Creates a PAT #GstMpegtsSection from the @programs array of #GstMpegtsPatPrograms - - - a #GstMpegtsSection - - - - - an array of #GstMpegtsPatProgram - - - - - - Transport stream ID of the PAT - - - - - - Creates a #GstMpegtsSection from @pmt that is bound to @pid - - - #GstMpegtsSection - - - - - a #GstMpegtsPMT to create a #GstMpegtsSection from - - - - The PID that the #GstMpegtsPMT belongs to - - - - - - Ownership of @sit is taken. The data in @sit is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsSCTESIT to create the #GstMpegtsSection from - - - - - - - - - Ownership of @sdt is taken. The data in @sdt is managed by the #GstMpegtsSection - - - the #GstMpegtsSection - - - - - a #GstMpegtsSDT to create the #GstMpegtsSection from - - - - - - - - - - - - - - - - - - - - diff --git a/gir-files/GstNet-1.0.gir b/gir-files/GstNet-1.0.gir deleted file mode 100644 index f723c1954..000000000 --- a/gir-files/GstNet-1.0.gir +++ /dev/null @@ -1,914 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The size of the packets sent between network clocks. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstNetAddressMeta can be used to store a network address (a #GSocketAddress) -in a #GstBuffer so that it network elements can track the to and from address -of the buffer. - - - the parent type - - - - a #GSocketAddress stored as metadata - - - - - - - - - - - #GstNetClientClock implements a custom #GstClock that synchronizes its time -to a remote time provider such as #GstNetTimeProvider. #GstNtpClock -implements a #GstClock that synchronizes its time to a remote NTPv4 server. - -A new clock is created with gst_net_client_clock_new() or -gst_ntp_clock_new(), which takes the address and port of the remote time -provider along with a name and an initial time. - -This clock will poll the time provider and will update its calibration -parameters based on the local and remote observations. - -The "round-trip" property limits the maximum round trip packets can take. - -Various parameters of the clock can be configured with the parent #GstClock -"timeout", "window-size" and "window-threshold" object properties. - -A #GstNetClientClock and #GstNtpClock is typically set on a #GstPipeline with -gst_pipeline_use_clock(). - -If you set a #GstBus on the clock via the "bus" object property, it will -send @GST_MESSAGE_ELEMENT messages with an attached #GstStructure containing -statistics about clock accuracy and network traffic. - - - Create a new #GstNetClientClock that will report the time -provided by the #GstNetTimeProvider on @remote_address and -@remote_port. - - - a new #GstClock that receives a time from the remote -clock. - - - - - a name for the clock - - - - the address or hostname of the remote clock provider - - - - the port of the remote clock provider - - - - initial time of the clock - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstNetControlMessageMeta can be used to store control messages (ancillary -data) which was received with or is to be sent alongside the buffer data. -When used with socket sinks and sources which understand this meta it allows -sending and receiving ancillary data such as unix credentials (See -#GUnixCredentialsMessage) and Unix file descriptions (See #GUnixFDMessage). - - - the parent type - - - - a #GSocketControlMessage stored as metadata - - - - - - - - - - - Various functions for receiving, sending an serializing #GstNetTimePacket -structures. - - - the local time when this packet was sent - - - - the remote time observation - - - - Creates a new #GstNetTimePacket from a buffer received over the network. The -caller is responsible for ensuring that @buffer is at least -#GST_NET_TIME_PACKET_SIZE bytes long. - -If @buffer is %NULL, the local and remote times will be set to -#GST_CLOCK_TIME_NONE. - -MT safe. Caller owns return value (gst_net_time_packet_free to free). - - - The new #GstNetTimePacket. - - - - - a buffer from which to construct the packet, or NULL - - - - - - - - Make a copy of @packet. - - - a copy of @packet, free with gst_net_time_packet_free(). - - - - - the #GstNetTimePacket - - - - - - Free @packet. - - - - - - - the #GstNetTimePacket - - - - - - Sends a #GstNetTimePacket over a socket. - -MT safe. - - - TRUE if successful, FALSE in case an error occurred. - - - - - the #GstNetTimePacket to send - - - - socket to send the time packet on - - - - address to send the time packet to - - - - - - Serialized a #GstNetTimePacket into a newly-allocated sequence of -#GST_NET_TIME_PACKET_SIZE bytes, in network byte order. The value returned is -suitable for passing to write(2) or sendto(2) for communication over the -network. - -MT safe. Caller owns return value (g_free to free). - - - A newly allocated sequence of #GST_NET_TIME_PACKET_SIZE bytes. - - - - - the #GstNetTimePacket - - - - - - Receives a #GstNetTimePacket over a socket. Handles interrupted system -calls, but otherwise returns NULL on error. - - - a new #GstNetTimePacket, or NULL on error. Free - with gst_net_time_packet_free() when done. - - - - - socket to receive the time packet on - - - - address of variable to return sender address - - - - - - - This object exposes the time of a #GstClock on the network. - -A #GstNetTimeProvider is created with gst_net_time_provider_new() which -takes a #GstClock, an address and a port number as arguments. - -After creating the object, a client clock such as #GstNetClientClock can -query the exposed clock over the network for its values. - -The #GstNetTimeProvider typically wraps the clock used by a #GstPipeline. - - - - Allows network clients to get the current time of @clock. - - - the new #GstNetTimeProvider, or NULL on error - - - - - a #GstClock to export over the network - - - - an address to bind on as a dotted quad - (xxx.xxx.xxx.xxx), IPv6 address, or NULL to bind to all addresses - - - - a port to bind on, or 0 to let the kernel choose - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Create a new #GstNtpClock that will report the time provided by -the NTPv4 server on @remote_address and @remote_port. - - - a new #GstClock that receives a time from the remote -clock. - - - - - a name for the clock - - - - the address or hostname of the remote clock provider - - - - the port of the remote clock provider - - - - initial time of the clock - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PTP clock identification that can be passed to gst_ptp_init() to -automatically select one based on the MAC address of interfaces - - - - - - - - - - - - - - - - - - - - - GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only -mode, that allows a GStreamer pipeline to synchronize to a PTP network -clock in some specific domain. - -The PTP subsystem can be initialized with gst_ptp_init(), which then starts -a helper process to do the actual communication via the PTP ports. This is -required as PTP listens on ports < 1024 and thus requires special -privileges. Once this helper process is started, the main process will -synchronize to all PTP domains that are detected on the selected -interfaces. - -gst_ptp_clock_new() then allows to create a GstClock that provides the PTP -time from a master clock inside a specific PTP domain. This clock will only -return valid timestamps once the timestamps in the PTP domain are known. To -check this, you can use gst_clock_wait_for_sync(), the GstClock::synced -signal and gst_clock_is_synced(). - -To gather statistics about the PTP clock synchronization, -gst_ptp_statistics_callback_add() can be used. This gives the application -the possibility to collect all kinds of statistics from the clock -synchronization. - - - Creates a new PTP clock instance that exports the PTP time of the master -clock in @domain. This clock can be slaved to other clocks as needed. - -If gst_ptp_init() was not called before, this will call gst_ptp_init() with -default parameters. - -This clock only returns valid timestamps after it received the first -times from the PTP master clock on the network. Once this happens the -GstPtpClock::internal-clock property will become non-NULL. You can -check this with gst_clock_wait_for_sync(), the GstClock::synced signal and -gst_clock_is_synced(). - - - A new #GstClock - - - - - Name of the clock - - - - PTP domain - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Opaque #GstPtpClockClass structure. - - - parented to #GstSystemClockClass - - - - - - - - - - - - - The statistics can be the following structures: - -GST_PTP_STATISTICS_NEW_DOMAIN_FOUND: -"domain" G_TYPE_UINT The domain identifier of the domain -"clock" GST_TYPE_CLOCK The internal clock that is slaved to the - PTP domain - -GST_PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED: -"domain" G_TYPE_UINT The domain identifier of the domain -"master-clock-id" G_TYPE_UINT64 PTP clock identifier of the selected master - clock -"master-clock-port" G_TYPE_UINT PTP port number of the selected master clock -"grandmaster-clock-id" G_TYPE_UINT64 PTP clock identifier of the grandmaster clock - -GST_PTP_STATISTICS_PATH_DELAY_MEASURED: -"domain" G_TYPE_UINT The domain identifier of the domain -"mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay -"mean-path-delay" GST_TYPE_CLOCK_TIME Latest mean path delay -"delay-request-delay" GST_TYPE_CLOCK_TIME Delay of DELAY_REQ / DELAY_RESP messages - -GST_PTP_STATISTICS_TIME_UPDATED: -"domain" G_TYPE_UINT The domain identifier of the domain -"mean-path-delay-avg" GST_TYPE_CLOCK_TIME Average mean path delay -"local-time" GST_TYPE_CLOCK_TIME Local time that corresponds to ptp-time -"ptp-time" GST_TYPE_CLOCK_TIME Newly measured PTP time at local-time -"estimated-ptp-time" GST_TYPE_CLOCK_TIME Estimated PTP time based on previous measurements -"discontinuity" G_TYPE_INT64 Difference between estimated and measured PTP time -"synced" G_TYPE_BOOLEAN Currently synced to the remote clock -"r-squared" G_TYPE_DOUBLE R² of clock estimation regression -"internal-time" GST_TYPE_CLOCK_TIME Internal time clock parameter -"external-time" GST_TYPE_CLOCK_TIME External time clock parameter -"rate-num" G_TYPE_UINT64 Internal/external rate numerator -"rate-den" G_TYPE_UINT64 Internal/external rate denominator -"rate" G_TYPE_DOUBLE Internal/external rate - -If %FALSE is returned, the callback is removed and never called again. - - - - - - - PTP domain identifier - - - - New statistics - - - - Data passed to gst_ptp_statistics_callback_add() - - - - - - Attaches @addr as metadata in a #GstNetAddressMeta to @buffer. - - - a #GstNetAddressMeta connected to @buffer - - - - - a #GstBuffer - - - - a @GSocketAddress to connect to @buffer - - - - - - Attaches @message as metadata in a #GstNetControlMessageMeta to @buffer. - - - a #GstNetControlMessageMeta connected to @buffer - - - - - a #GstBuffer - - - - a @GSocketControlMessage to attach to @buffer - - - - - - Find the #GstNetAddressMeta on @buffer. - - - the #GstNetAddressMeta or %NULL when there -is no such metadata on @buffer. - - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Receives a #GstNetTimePacket over a socket. Handles interrupted system -calls, but otherwise returns NULL on error. - - - a new #GstNetTimePacket, or NULL on error. Free - with gst_net_time_packet_free() when done. - - - - - socket to receive the time packet on - - - - address of variable to return sender address - - - - - - Configures IP_TOS value of socket, i.e. sets QoS DSCP. - - - TRUE if successful, FALSE in case an error occurred. - - - - - Socket to configure - - - - QoS DSCP value - - - - - - Deinitialize the GStreamer PTP subsystem and stop the PTP clock. If there -are any remaining GstPtpClock instances, they won't be further synchronized -to the PTP network clock. - - - - - - - Initialize the GStreamer PTP subsystem and create a PTP ordinary clock in -slave-only mode for all domains on the given @interfaces with the -given @clock_id. - -If @clock_id is %GST_PTP_CLOCK_ID_NONE, a clock id is automatically -generated from the MAC address of the first network interface. - -This function is automatically called by gst_ptp_clock_new() with default -parameters if it wasn't called before. - - - %TRUE if the GStreamer PTP clock subsystem could be initialized. - - - - - PTP clock id of this process' clock or %GST_PTP_CLOCK_ID_NONE - - - - network interfaces to run the clock on - - - - - - - - Check if the GStreamer PTP clock subsystem is initialized. - - - %TRUE if the GStreamer PTP clock subsystem is initialized. - - - - - Check if PTP clocks are generally supported on this system, and if previous -initializations did not fail. - - - %TRUE if PTP clocks are generally supported on this system, and -previous initializations did not fail. - - - - - Installs a new statistics callback for gathering PTP statistics. See -GstPtpStatisticsCallback for a list of statistics that are provided. - - - Id for the callback that can be passed to -gst_ptp_statistics_callback_remove() - - - - - GstPtpStatisticsCallback to call - - - - Data to pass to the callback - - - - GDestroyNotify to destroy the data - - - - - - Removes a PTP statistics callback that was previously added with -gst_ptp_statistics_callback_add(). - - - - - - - Callback id to remove - - - - - - diff --git a/gir-files/GstPbutils-1.0.gir b/gir-files/GstPbutils-1.0.gir deleted file mode 100644 index 1eb83bc64..000000000 --- a/gir-files/GstPbutils-1.0.gir +++ /dev/null @@ -1,4107 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A baseclass for scopes (visualizers). It takes care of re-fitting the -audio-rate to video-rate and handles renegotiation (downstream video size -changes). - -It also provides several background shading effects. These effects are -applied to a previous picture before the `render()` implementation can draw a -new frame. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Different types of supported background shading functions. - - no shading - - - plain fading - - - fade and move up - - - fade and move down - - - fade and move left - - - fade and move right - - - fade and move horizontally out - - - fade and move horizontally in - - - fade and move vertically out - - - fade and move vertically in - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstDiscoverer is a utility object which allows to get as much -information as possible from one or many URIs. - -It provides two APIs, allowing usage in blocking or non-blocking mode. - -The blocking mode just requires calling gst_discoverer_discover_uri() -with the URI one wishes to discover. - -The non-blocking mode requires a running #GMainLoop iterating a -#GMainContext, where one connects to the various signals, appends the -URIs to be processed (through gst_discoverer_discover_uri_async()) and then -asks for the discovery to begin (through gst_discoverer_start()). -By default this will use the GLib default main context unless you have -set a custom context using g_main_context_push_thread_default(). - -All the information is returned in a #GstDiscovererInfo structure. - - - Creates a new #GstDiscoverer with the provided timeout. - - - The new #GstDiscoverer. -If an error occurred when creating the discoverer, @err will be set -accordingly and %NULL will be returned. If @err is set, the caller must -free it when no longer needed using g_error_free(). - - - - - timeout per file, in nanoseconds. Allowed are values between - one second (#GST_SECOND) and one hour (3600 * #GST_SECOND) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Synchronously discovers the given @uri. - -A copy of @uri will be made internally, so the caller can safely g_free() -afterwards. - - - the result of the scanning. Can be %NULL if an -error occurred. - - - - - A #GstDiscoverer - - - - The URI to run on. - - - - - - Appends the given @uri to the list of URIs to discoverer. The actual -discovery of the @uri will only take place if gst_discoverer_start() has -been called. - -A copy of @uri will be made internally, so the caller can safely g_free() -afterwards. - - - %TRUE if the @uri was successfully appended to the list of pending -uris, else %FALSE - - - - - A #GstDiscoverer - - - - the URI to add. - - - - - - Allow asynchronous discovering of URIs to take place. -A #GMainLoop must be available for #GstDiscoverer to properly work in -asynchronous mode. - - - - - - - A #GstDiscoverer - - - - - - Stop the discovery of any pending URIs and clears the list of -pending URIS (if any). - - - - - - - A #GstDiscoverer - - - - - - The duration (in nanoseconds) after which the discovery of an individual -URI will timeout. - -If the discovery of a URI times out, the %GST_DISCOVERER_TIMEOUT will be -set on the result flags. - - - - - - - - - - - - - - - - - - Will be emitted in async mode when all information on a URI could be -discovered, or an error occurred. - -When an error occurs, @info might still contain some partial information, -depending on the circumstances of the error. - - - - - - the results #GstDiscovererInfo - - - - #GError, which will be non-NULL - if an error occurred during - discovery. You must not free - this #GError, it will be freed by - the discoverer. - - - - - - Will be emitted in async mode when all pending URIs have been processed. - - - - - - This signal is emitted after the source element has been created for, so -the URI being discovered, so it can be configured by setting additional -properties (e.g. set a proxy server for an http source, or set the device -and read speed for an audio cd source). - -This signal is usually emitted from the context of a GStreamer streaming -thread. - - - - - - source element - - - - - - Will be emitted when the discover starts analyzing the pending URIs - - - - - - - #GstDiscovererStreamInfo specific to audio streams. - - - - the average or nominal bitrate of the stream in bits/second. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the channel-mask of the stream, refer to -gst_audio_channel_positions_from_mask() for more -information. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the number of channels in the stream. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the number of bits used per sample in each channel. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the language of the stream, or NULL if unknown. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the maximum bitrate of the stream in bits/second. - - - - - a #GstDiscovererAudioInfo - - - - - - - - the sample rate of the stream in Hertz. - - - - - a #GstDiscovererAudioInfo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstDiscovererStreamInfo specific to container streams. - - - - the list of -#GstDiscovererStreamInfo this container stream offers. -Free with gst_discoverer_stream_info_list_free() after usage. - - - - - - - a #GstDiscovererStreamInfo - - - - - - - Structure containing the information of a URI analyzed by #GstDiscoverer. - - Parses a #GVariant as produced by gst_discoverer_info_to_variant() -back to a #GstDiscovererInfo. - - - A newly-allocated #GstDiscovererInfo. - - - - - A #GVariant to deserialize into a #GstDiscovererInfo. - - - - - - - - A copy of the #GstDiscovererInfo - - - - - a #GstDiscovererInfo - - - - - - Finds all the #GstDiscovererAudioInfo contained in @info - - - A #GList of -matching #GstDiscovererStreamInfo. The caller should free it with -gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - - - Finds all the #GstDiscovererContainerInfo contained in @info - - - A #GList of -matching #GstDiscovererStreamInfo. The caller should free it with -gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - - - - - the duration of the URI in #GstClockTime (nanoseconds). - - - - - a #GstDiscovererInfo - - - - - - - - whether the URI is live. - - - - - a #GstDiscovererInfo - - - - - - This functions is deprecated since version 1.4, use -#gst_discoverer_info_get_missing_elements_installer_details - - - Miscellaneous information stored as a #GstStructure -(for example: information about missing plugins). If you wish to use the -#GstStructure after the life-time of @info, you will need to copy it. - - - - - a #GstDiscovererInfo - - - - - - Get the installer details for missing elements - - - An array of strings -containing information about how to install the various missing elements -for @info to be usable. If you wish to use the strings after the life-time -of @info, you will need to copy them. - - - - - - - a #GstDiscovererStreamInfo to retrieve installer detail -for the missing element - - - - - - - - the result of the discovery as a #GstDiscovererResult. - - - - - a #GstDiscovererInfo - - - - - - - - the whether the URI is seekable. - - - - - a #GstDiscovererInfo - - - - - - - - the structure (or topology) of the URI as a -#GstDiscovererStreamInfo. -This structure can be traversed to see the original hierarchy. Unref with -gst_discoverer_stream_info_unref() after usage. - - - - - a #GstDiscovererInfo - - - - - - - - the list of -all streams contained in the #info. Free after usage -with gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - - - Finds the #GstDiscovererStreamInfo contained in @info that match the -given @streamtype. - - - A #GList of -matching #GstDiscovererStreamInfo. The caller should free it with -gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - a #GType derived from #GstDiscovererStreamInfo - - - - - - Finds all the #GstDiscovererSubtitleInfo contained in @info - - - A #GList of -matching #GstDiscovererStreamInfo. The caller should free it with -gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - - - - - all tags contained in the URI. If you wish to use -the tags after the life-time of @info, you will need to copy them. - - - - - a #GstDiscovererInfo - - - - - - - - TOC contained in the URI. If you wish to use -the TOC after the life-time of @info, you will need to copy it. - - - - - a #GstDiscovererInfo - - - - - - - - the URI to which this information corresponds to. -Copy it if you wish to use it after the life-time of @info. - - - - - a #GstDiscovererInfo - - - - - - Finds all the #GstDiscovererVideoInfo contained in @info - - - A #GList of -matching #GstDiscovererStreamInfo. The caller should free it with -gst_discoverer_stream_info_list_free(). - - - - - - - a #GstDiscovererInfo - - - - - - Serializes @info to a #GVariant that can be parsed again -through gst_discoverer_info_from_variant(). - -Note that any #GstToc (s) that might have been discovered will not be serialized -for now. - - - A newly-allocated #GVariant representing @info. - - - - - A #GstDiscovererInfo - - - - A combination of #GstDiscovererSerializeFlags to specify -what needs to be serialized. - - - - - - - - - - Result values for the discovery process. - - The discovery was successful - - - the URI is invalid - - - an error happened and the GError is set - - - the discovery timed-out - - - the discoverer was already discovering a file - - - Some plugins are missing for full discovery - - - - You can use these flags to control what is serialized by -gst_discoverer_info_to_variant() - - Serialize only basic information, excluding -caps, tags and miscellaneous information - - - Serialize the caps for each stream - - - Serialize the tags for each stream - - - Serialize miscellaneous information for each stream - - - Serialize all the available info, including -caps, tags and miscellaneous information - - - - Base structure for information concerning a media stream. Depending on the -stream type, one can find more media-specific information in -#GstDiscovererAudioInfo, #GstDiscovererVideoInfo, and -#GstDiscovererContainerInfo. - -The #GstDiscovererStreamInfo represents the topology of the stream. Siblings -can be iterated over with gst_discoverer_stream_info_get_next() and -gst_discoverer_stream_info_get_previous(). Children (sub-streams) of a -stream can be accessed using the #GstDiscovererContainerInfo API. - -As a simple example, if you run #GstDiscoverer on an AVI file with one audio -and one video stream, you will get a #GstDiscovererContainerInfo -corresponding to the AVI container, which in turn will have a -#GstDiscovererAudioInfo sub-stream and a #GstDiscovererVideoInfo sub-stream -for the audio and video streams respectively. - - Decrements the reference count of all contained #GstDiscovererStreamInfo -and fress the #GList. - - - - - - - a #GList of #GstDiscovererStreamInfo - - - - - - - - - - the #GstCaps of the stream. Unref with -#gst_caps_unref after usage. - - - - - a #GstDiscovererStreamInfo - - - - - - This functions is deprecated since version 1.4, use -#gst_discoverer_info_get_missing_elements_installer_details - - - additional information regarding the stream (for -example codec version, profile, etc..). If you wish to use the #GstStructure -after the life-time of @info you will need to copy it. - - - - - a #GstDiscovererStreamInfo - - - - - - - - the next #GstDiscovererStreamInfo in a chain. %NULL -for final streams. -Unref with #gst_discoverer_stream_info_unref after usage. - - - - - a #GstDiscovererStreamInfo - - - - - - - - the previous #GstDiscovererStreamInfo in a chain. -%NULL for starting points. Unref with #gst_discoverer_stream_info_unref -after usage. - - - - - a #GstDiscovererStreamInfo - - - - - - - - the stream ID of this stream. If you wish to -use the stream ID after the life-time of @info you will need to copy it. - - - - - a #GstDiscovererStreamInfo - - - - - - - - a human readable name for the stream type of the given @info (ex : "audio", -"container",...). - - - - - a #GstDiscovererStreamInfo - - - - - - - - the tags contained in this stream. If you wish to -use the tags after the life-time of @info you will need to copy them. - - - - - a #GstDiscovererStreamInfo - - - - - - - - the TOC contained in this stream. If you wish to -use the TOC after the life-time of @info you will need to copy it. - - - - - a #GstDiscovererStreamInfo - - - - - - - #GstDiscovererStreamInfo specific to subtitle streams (this includes text and -image based ones). - - - - the language of the stream, or NULL if unknown. - - - - - a #GstDiscovererSubtitleInfo - - - - - - - #GstDiscovererStreamInfo specific to video streams (this includes images). - - - - the average or nominal bitrate of the video stream in bits/second. - - - - - a #GstDiscovererVideoInfo - - - - - - - - the depth in bits of the video stream. - - - - - a #GstDiscovererVideoInfo - - - - - - - - the framerate of the video stream (denominator). - - - - - a #GstDiscovererVideoInfo - - - - - - - - the framerate of the video stream (numerator). - - - - - a #GstDiscovererVideoInfo - - - - - - - - the height of the video stream in pixels. - - - - - a #GstDiscovererVideoInfo - - - - - - - - the maximum bitrate of the video stream in bits/second. - - - - - a #GstDiscovererVideoInfo - - - - - - - - the Pixel Aspect Ratio (PAR) of the video stream (denominator). - - - - - a #GstDiscovererVideoInfo - - - - - - - - the Pixel Aspect Ratio (PAR) of the video stream (numerator). - - - - - a #GstDiscovererVideoInfo - - - - - - - - the width of the video stream in pixels. - - - - - a #GstDiscovererVideoInfo - - - - - - - - %TRUE if the video stream corresponds to an image (i.e. only contains -one frame). - - - - - a #GstDiscovererVideoInfo - - - - - - - - %TRUE if the stream is interlaced, else %FALSE. - - - - - a #GstDiscovererVideoInfo - - - - - - - - - - - - - - #GstEncodingTarget category for recording and capture. -Targets within this category are optimized for low latency encoding. - - - - - #GstEncodingTarget category for device-specific targets. -The name of the target will usually be the constructor and model of the device, -and that target will contain #GstEncodingProfiles suitable for that device. - - - - - #GstEncodingTarget category for file extensions. -The name of the target will be the name of the file extensions possible -for a particular target. Those targets are defining like 'default' formats -usually used for a particular file extension. - - - - - #GstEncodingTarget category for online-services. -The name of the target will usually be the name of the online service -and that target will contain #GstEncodingProfiles suitable for that online -service. - - - - - #GstEncodingTarget category for storage, archiving and editing targets. -Those targets can be lossless and/or provide very fast random access content. -The name of the target will usually be the container type or editing target, -and that target will contain #GstEncodingProfiles suitable for editing or -storage. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Variant of #GstEncodingProfile for audio streams. - - - Creates a new #GstEncodingAudioProfile - -All provided allocatable arguments will be internally copied, so can be -safely freed/unreferenced after calling this method. - - - the newly created #GstEncodingAudioProfile. - - - - - the #GstCaps - - - - the preset(s) to use on the encoder, can be %NULL - - - - the #GstCaps used to restrict the input to the encoder, can be -NULL. See gst_encoding_profile_get_restriction() for more details. - - - - the number of time this stream must be used. 0 means any number of - times (including never) - - - - - - - - - - Encoding profiles for containers. Keeps track of a list of #GstEncodingProfile - - - Creates a new #GstEncodingContainerProfile. - - - The newly created #GstEncodingContainerProfile. - - - - - The name of the container profile, can be %NULL - - - - The description of the container profile, - can be %NULL - - - - The format to use for this profile - - - - The preset to use for this profile. - - - - - - Add a #GstEncodingProfile to the list of profiles handled by @container. - -No copy of @profile will be made, if you wish to use it elsewhere after this -method you should increment its reference count. - - - %TRUE if the @stream was properly added, else %FALSE. - - - - - the #GstEncodingContainerProfile to use - - - - the #GstEncodingProfile to add. - - - - - - Checks if @container contains a #GstEncodingProfile identical to -@profile. - - - %TRUE if @container contains a #GstEncodingProfile identical -to @profile, else %FALSE. - - - - - a #GstEncodingContainerProfile - - - - a #GstEncodingProfile - - - - - - - - -the list of contained #GstEncodingProfile. - - - - - - - a #GstEncodingContainerProfile - - - - - - - - - - The opaque base class object for all encoding profiles. This contains generic -information like name, description, format and preset. - - - Find the #GstEncodingProfile with the specified name and category. - - - The matching #GstEncodingProfile or %NULL. - - - - - The name of the target - - - - The name of the profile, if %NULL -provided, it will default to the encoding profile called `default`. - - - - The target category. Can be %NULL - - - - - - Creates a #GstEncodingProfile matching the formats from the given -#GstDiscovererInfo. Streams other than audio or video (eg, -subtitles), are currently ignored. - - - The new #GstEncodingProfile or %NULL. - - - - - The #GstDiscovererInfo to read from - - - - - - Makes a deep copy of @self - - - The copy of @self - - - - - The #GstEncodingProfile to copy - - - - - - Get whether the format that has been negotiated in at some point can be renegotiated -later during the encoding. - - - - - - - a #GstEncodingProfile - - - - - - - - the description of the profile, can be %NULL. - - - - - a #GstEncodingProfile - - - - - - - - a suitable file extension for @profile, or NULL. - - - - - a #GstEncodingProfile - - - - - - - - the #GstCaps corresponding to the media format used -in the profile. Unref after usage. - - - - - a #GstEncodingProfile - - - - - - Computes the full output caps that this @profile will be able to consume. - - - The full caps the given @profile can consume. Call -gst_caps_unref() when you are done with the caps. - - - - - a #GstEncodingProfile - - - - - - - - the name of the profile, can be %NULL. - - - - - a #GstEncodingProfile - - - - - - - - The number of times the profile is used in its parent -container profile. If 0, it is not a mandatory stream. - - - - - a #GstEncodingProfile - - - - - - - - the name of the #GstPreset to be used in the profile. -This is the name that has been set when saving the preset. - - - - - a #GstEncodingProfile - - - - - - - - the name of the #GstPreset factory to be used in the profile. - - - - - a #GstEncodingProfile - - - - - - - - The restriction #GstCaps to apply before the encoder -that will be used in the profile. The fields present in restriction caps are -properties of the raw stream (that is before encoding), such as height and -width for video and depth and sampling rate for audio. Does not apply to -#GstEncodingContainerProfile (since there is no corresponding raw stream). -Can be %NULL. Unref after usage. - - - - - a #GstEncodingProfile - - - - - - - - #TRUE if the stream represented by @profile should use a single -segment before the encoder, #FALSE otherwise. This means that buffers will be retimestamped -and segments will be eat so as to appear as one segment. - - - - - a #GstEncodingProfile - - - - - - - - the human-readable name of the type of @profile. - - - - - a #GstEncodingProfile - - - - - - - - - - - - - - - - - Checks whether the two #GstEncodingProfile are equal - - - %TRUE if @a and @b are equal, else %FALSE. - - - - - a #GstEncodingProfile - - - - a #GstEncodingProfile - - - - - - Sets whether the format that has been negotiated in at some point can be renegotiated -later during the encoding. - - - - - - - a #GstEncodingProfile - - - - Whether the format that has been negotiated first can be renegotiated -during the encoding - - - - - - Set @description as the given description for the @profile. A copy of -@description will be made internally. - - - - - - - a #GstEncodingProfile - - - - the description to set on the profile - - - - - - Set whether the profile should be used or not. - - - - - - - a #GstEncodingProfile - - - - %FALSE to disable @profile, %TRUE to enable it - - - - - - Sets the media format used in the profile. - - - - - - - a #GstEncodingProfile - - - - the media format to use in the profile. - - - - - - Set @name as the given name for the @profile. A copy of @name will be made -internally. - - - - - - - a #GstEncodingProfile - - - - the name to set on the profile - - - - - - Set the number of time the profile is used in its parent -container profile. If 0, it is not a mandatory stream - - - - - - - a #GstEncodingProfile - - - - the number of time the profile can be used - - - - - - Sets the name of the #GstElement that implements the #GstPreset interface -to use for the profile. -This is the name that has been set when saving the preset. - - - - - - - a #GstEncodingProfile - - - - the element preset to use - - - - - - Sets the name of the #GstPreset's factory to be used in the profile. - - - - - - - a #GstEncodingProfile - - - - The name of the preset to use in this @profile. - - - - - - Set the restriction #GstCaps to apply before the encoder -that will be used in the profile. See gst_encoding_profile_get_restriction() -for more about restrictions. Does not apply to #GstEncodingContainerProfile. - - - - - - - a #GstEncodingProfile - - - - the restriction to apply - - - - - - If using a single segment, buffers will be retimestamped and segments will be -eat so as to appear as one segment. - -> *NOTE*: Single segment is not property supported when using -> #encodebin:avoid-reencoding - - - - - - - a #GstEncodingProfile - - - - #TRUE if the stream represented by @profile should use a -single segment before the encoder, #FALSE otherwise. - - - - - - - - - - - - - Collection of #GstEncodingProfile for a specific target or use-case. - -When being stored/loaded, targets come from a specific category, like -#GST_ENCODING_CATEGORY_DEVICE. - - Creates a new #GstEncodingTarget. - -The name and category can only consist of lowercase ASCII letters for the -first character, followed by either lowercase ASCII letters, digits or -hyphens ('-'). - -The @category *should* be one of the existing -well-defined categories, like #GST_ENCODING_CATEGORY_DEVICE, but it -*can* be a application or user specific category if -needed. - - - The newly created #GstEncodingTarget or %NULL if -there was an error. - - - - - The name of the target. - - - - The name of the category to which this @target -belongs. For example: #GST_ENCODING_CATEGORY_DEVICE. - - - - A description of #GstEncodingTarget in the -current locale. - - - - A #GList of -#GstEncodingProfile. - - - - - - - - Searches for the #GstEncodingTarget with the given name, loads it -and returns it. - -If the category name is specified only targets from that category will be -searched for. - - - The #GstEncodingTarget if available, else %NULL. - - - - - the name of the #GstEncodingTarget to load (automatically -converted to lower case internally as capital letters are not -valid for target names). - - - - the name of the target category, like -#GST_ENCODING_CATEGORY_DEVICE. Can be %NULL - - - - - - Opens the provided file and returns the contained #GstEncodingTarget. - - - The #GstEncodingTarget contained in the file, else -%NULL - - - - - The file location to load the #GstEncodingTarget from - - - - - - Adds the given @profile to the @target. Each added profile must have -a unique name within the profile. - -The @target will steal a reference to the @profile. If you wish to use -the profile after calling this method, you should increase its reference -count. - - - %TRUE if the profile was added, else %FALSE. - - - - - the #GstEncodingTarget to add a profile to - - - - the #GstEncodingProfile to add - - - - - - - - The category of the @target. For example: -#GST_ENCODING_CATEGORY_DEVICE. - - - - - a #GstEncodingTarget - - - - - - - - The description of the @target. - - - - - a #GstEncodingTarget - - - - - - - - The name of the @target. - - - - - a #GstEncodingTarget - - - - - - - - The path to the @target file. - - - - - a #GstEncodingTarget - - - - - - - - The matching #GstEncodingProfile, or %NULL. - - - - - a #GstEncodingTarget - - - - the name of the profile to retrieve - - - - - - - - A list of -#GstEncodingProfile(s) this @target handles. - - - - - - - a #GstEncodingTarget - - - - - - Saves the @target to a default user-local directory. - - - %TRUE if the target was correctly saved, else %FALSE. - - - - - a #GstEncodingTarget - - - - - - Saves the @target to the provided file location. - - - %TRUE if the target was correctly saved, else %FALSE. - - - - - a #GstEncodingTarget - - - - the location to store the @target at. - - - - - - - Variant of #GstEncodingProfile for video streams, allows specifying the @pass. - - - Creates a new #GstEncodingVideoProfile - -All provided allocatable arguments will be internally copied, so can be -safely freed/unreferenced after calling this method. - -If you wish to control the pass number (in case of multi-pass scenarios), -please refer to the gst_encoding_video_profile_set_pass() documentation. - -If you wish to use/force a constant framerate please refer to the -gst_encoding_video_profile_set_variableframerate() documentation. - - - the newly created #GstEncodingVideoProfile. - - - - - the #GstCaps - - - - the preset(s) to use on the encoder, can be %NULL - - - - the #GstCaps used to restrict the input to the encoder, can be -NULL. See gst_encoding_profile_get_restriction() for more details. - - - - the number of time this stream must be used. 0 means any number of - times (including never) - - - - - - Get the pass number if this is part of a multi-pass profile. - - - The pass number. Starts at 1 for multi-pass. 0 if this is -not a multi-pass profile - - - - - a #GstEncodingVideoProfile - - - - - - > *NOTE*: Fixed framerate won't be enforced when #encodebin:avoid-reencoding -> is set. - - - Whether non-constant video framerate is allowed for encoding. - - - - - a #GstEncodingVideoProfile - - - - - - Sets the pass number of this video profile. The first pass profile should have -this value set to 1. If this video profile isn't part of a multi-pass profile, -you may set it to 0 (the default value). - - - - - - - a #GstEncodingVideoProfile - - - - the pass number for this profile - - - - - - If set to %TRUE, then the incoming stream will be allowed to have non-constant -framerate. If set to %FALSE (default value), then the incoming stream will -be normalized by dropping/duplicating frames in order to produce a -constance framerate. - - - - - - - a #GstEncodingVideoProfile - - - - a boolean - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Opaque context structure for the plugin installation. Use the provided -API to set details on it. - - - Creates a new #GstInstallPluginsContext. - - - a new #GstInstallPluginsContext. Free with -gst_install_plugins_context_free() when no longer needed - - - - - Copies a #GstInstallPluginsContext. - - - A copy of @ctx - - - - - a #GstInstallPluginsContext - - - - - - Frees a #GstInstallPluginsContext. - - - - - - - a #GstInstallPluginsContext - - - - - - This function is used to tell the external installer process whether it -should ask for confirmation or not before searching for missing plugins. - -If set, this option will be passed to the installer via a ---interaction=[show-confirm-search|hide-confirm-search] command line option. - - - - - - - a #GstInstallPluginsContext - - - - whether to ask for confirmation before searching for plugins - - - - - - This function is used to pass the calling application's desktop file ID to -the external installer process. - -A desktop file ID is the basename of the desktop file, including the -.desktop extension. - -If set, the desktop file ID will be passed to the installer via a ---desktop-id= command line option. - - - - - - - a #GstInstallPluginsContext - - - - the desktop file ID of the calling application - - - - - - Sets the startup notification ID for the launched process. - -This is typically used to to pass the current X11 event timestamp to the -external installer process. - -Startup notification IDs are defined in the -[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - -If set, the ID will be passed to the installer via a ---startup-notification-id= command line option. - -GTK+/GNOME applications should be able to create a startup notification ID -like this: -|[ - timestamp = gtk_get_current_event_time (); - startup_id = g_strdup_printf ("_TIME%u", timestamp); -... -]| - - - - - - - a #GstInstallPluginsContext - - - - the startup notification ID - - - - - - This function is for X11-based applications (such as most Gtk/Qt -applications on linux/unix) only. You can use it to tell the external -installer the XID of your main application window. That way the installer -can make its own window transient to your application window during the -installation. - -If set, the XID will be passed to the installer via a --transient-for=XID -command line option. - -Gtk+/Gnome application should be able to obtain the XID of the top-level -window like this: -|[ -##include &lt;gtk/gtk.h&gt; -##ifdef GDK_WINDOWING_X11 -##include &lt;gdk/gdkx.h&gt; -##endif -... -##ifdef GDK_WINDOWING_X11 - xid = GDK_WINDOW_XWINDOW (GTK_WIDGET (application_window)-&gt;window); -##endif -... -]| - - - - - - - a #GstInstallPluginsContext - - - - the XWindow ID (XID) of the top-level application - - - - - - - The prototype of the callback function that will be called once the -external plugin installer program has returned. You only need to provide -a callback function if you are using the asynchronous interface. - - - - - - - whether the installation of the requested plugins succeeded or not - - - - the user data passed to gst_install_plugins_async() - - - - - - Result codes returned by gst_install_plugins_async() and -gst_install_plugins_sync(), and also the result code passed to the -#GstInstallPluginsResultFunc specified with gst_install_plugins_async(). - -These codes indicate success or failure of starting an external installer -program and to what extent the requested plugins could be installed. - - all of the requested plugins could be - installed - - - no appropriate installation candidate for - any of the requested plugins could be found. Only return this if nothing - has been installed. Return #GST_INSTALL_PLUGINS_PARTIAL_SUCCESS if - some (but not all) of the requested plugins could be installed. - - - an error occurred during the installation. If - this happens, the user has already seen an error message and another - one should not be displayed - - - some of the requested plugins could - be installed, but not all - - - the user has aborted the installation - - - the installer had an unclean exit code - (ie. death by signal) - - - the helper returned an invalid status code - - - returned by gst_install_plugins_async() to - indicate that everything went fine so far and the provided callback - will be called with the result of the installation later - - - some internal failure has - occurred when trying to start the installer - - - the helper script to call the - actual installer is not installed - - - a previously-started plugin - installation is still in progress, try again later - - - Convenience function to return the descriptive string associated -with a status code. This function returns English strings and -should not be used for user messages. It is here only to assist -in debugging. - - - a descriptive string for the status code in @ret - - - - - the return status code - - - - - - - - - - - - - - The major version of GStreamer's gst-plugins-base libraries at compile time. - - - - - The micro version of GStreamer's gst-plugins-base libraries at compile time. - - - - - The minor version of GStreamer's gst-plugins-base libraries at compile time. - - - - - The nano version of GStreamer's gst-plugins-base libraries at compile time. -Actual releases have 0, GIT versions have 1, prerelease versions have 2-... - - - - - Sets the level and profile on @caps if it can be determined from -@audio_config. See gst_codec_utils_aac_get_level() and -gst_codec_utils_aac_get_profile() for more details on the parameters. -@caps must be audio/mpeg caps with an "mpegversion" field of either 2 or 4. -If mpegversion is 4, the "base-profile" field is also set in @caps. - - - %TRUE if the level and profile could be set, %FALSE otherwise. - - - - - the #GstCaps to which level and profile fields are to be added - - - - a pointer to the AudioSpecificConfig - as specified in the Elementary Stream Descriptor (esds) - in ISO/IEC 14496-1. (See below for more details) - - - - - - Length of @audio_config in bytes - - - - - - Returns the channels of the given AAC stream. - - - The channels or 0 if the channel could not be determined. - - - - - a pointer to the AudioSpecificConfig - as specified in the Elementary Stream Descriptor (esds) - in ISO/IEC 14496-1. - - - - - - Length of @audio_config in bytes - - - - - - Translates the sample rate to the index corresponding to it in AAC spec. - - - The AAC index for this sample rate, -1 if the rate is not a -valid AAC sample rate. - - - - - Sample rate - - - - - - Determines the level of a stream as defined in ISO/IEC 14496-3. For AAC LC -streams, the constraints from the AAC audio profile are applied. For AAC -Main, LTP, SSR and others, the Main profile is used. - -The @audio_config parameter follows the following format, starting from the -most significant bit of the first byte: - - * Bit 0:4 contains the AudioObjectType (if this is 0x5, then the - real AudioObjectType is carried after the rate and channel data) - * Bit 5:8 contains the sample frequency index (if this is 0xf, then the - next 24 bits define the actual sample frequency, and subsequent - fields are appropriately shifted). - * Bit 9:12 contains the channel configuration - - - The level as a const string and %NULL if the level could not be -determined. - - - - - a pointer to the AudioSpecificConfig - as specified in the Elementary Stream Descriptor (esds) - in ISO/IEC 14496-1. - - - - - - Length of @audio_config in bytes - - - - - - Returns the profile of the given AAC stream as a string. The profile is -normally determined using the AudioObjectType field which is in the first -5 bits of @audio_config - - - The profile as a const string and %NULL if the profile could not be -determined. - - - - - a pointer to the AudioSpecificConfig - as specified in the Elementary Stream Descriptor (esds) - in ISO/IEC 14496-1. - - - - - - Length of @audio_config in bytes - - - - - - Translates the sample rate index found in AAC headers to the actual sample -rate. - - - The sample rate if sr_idx is valid, 0 otherwise. - - - - - a pointer to the AudioSpecificConfig - as specified in the Elementary Stream Descriptor (esds) - in ISO/IEC 14496-1. - - - - - - Length of @audio_config - - - - - - Translates the sample rate index found in AAC headers to the actual sample -rate. - - - The sample rate if @sr_idx is valid, 0 otherwise. - - - - - Sample rate index as from the AudioSpecificConfig (MPEG-4 - container) or ADTS frame header - - - - - - Sets the level and profile in @caps if it can be determined from @sps. See -gst_codec_utils_h264_get_level() and gst_codec_utils_h264_get_profile() -for more details on the parameters. - - - %TRUE if the level and profile could be set, %FALSE otherwise. - - - - - the #GstCaps to which the level and profile are to be added - - - - Pointer to the sequence parameter set for the stream. - - - - - - Length of the data available in @sps. - - - - - - Converts the level indication (level_idc) in the stream's -sequence parameter set into a string. The SPS is expected to have the -same format as for gst_codec_utils_h264_get_profile(). - - - The level as a const string, or %NULL if there is an error. - - - - - Pointer to the sequence parameter set for the stream. - - - - - - Length of the data available in @sps. - - - - - - Transform a level string from the caps into the level_idc - - - the level_idc or 0 if the level is unknown - - - - - A level string from caps - - - - - - Converts the profile indication (profile_idc) in the stream's -sequence parameter set into a string. The SPS is expected to have the -following format, as defined in the H.264 specification. The SPS is viewed -as a bitstream here, with bit 0 being the most significant bit of the first -byte. - -* Bit 0:7 - Profile indication -* Bit 8 - constraint_set0_flag -* Bit 9 - constraint_set1_flag -* Bit 10 - constraint_set2_flag -* Bit 11 - constraint_set3_flag -* Bit 12 - constraint_set3_flag -* Bit 13:15 - Reserved -* Bit 16:24 - Level indication - - - The profile as a const string, or %NULL if there is an error. - - - - - Pointer to the sequence parameter set for the stream. - - - - - - Length of the data available in @sps. - - - - - - Sets the level, tier and profile in @caps if it can be determined from -@profile_tier_level. See gst_codec_utils_h265_get_level(), -gst_codec_utils_h265_get_tier() and gst_codec_utils_h265_get_profile() -for more details on the parameters. - - - %TRUE if the level, tier, profile could be set, %FALSE otherwise. - - - - - the #GstCaps to which the level, tier and profile are to be added - - - - Pointer to the profile_tier_level - struct - - - - - - Length of the data available in @profile_tier_level. - - - - - - Converts the level indication (general_level_idc) in the stream's -profile_tier_level structure into a string. The profiel_tier_level is -expected to have the same format as for gst_codec_utils_h264_get_profile(). - - - The level as a const string, or %NULL if there is an error. - - - - - Pointer to the profile_tier_level - for the stream - - - - - - Length of the data available in @profile_tier_level. - - - - - - Transform a level string from the caps into the level_idc - - - the level_idc or 0 if the level is unknown - - - - - A level string from caps - - - - - - Converts the profile indication (general_profile_idc) in the stream's -profile_level_tier structure into a string. The profile_tier_level is -expected to have the following format, as defined in the H.265 -specification. The profile_tier_level is viewed as a bitstream here, -with bit 0 being the most significant bit of the first byte. - -* Bit 0:1 - general_profile_space -* Bit 2 - general_tier_flag -* Bit 3:7 - general_profile_idc -* Bit 8:39 - gernal_profile_compatibility_flags -* Bit 40 - general_progressive_source_flag -* Bit 41 - general_interlaced_source_flag -* Bit 42 - general_non_packed_constraint_flag -* Bit 43 - general_frame_only_constraint_flag -* Bit 44:87 - See below -* Bit 88:95 - general_level_idc - - - The profile as a const string, or %NULL if there is an error. - - - - - Pointer to the profile_tier_level - structure for the stream. - - - - - - Length of the data available in @profile_tier_level - - - - - - Converts the tier indication (general_tier_flag) in the stream's -profile_tier_level structure into a string. The profile_tier_level -is expected to have the same format as for gst_codec_utils_h264_get_profile(). - - - The tier as a const string, or %NULL if there is an error. - - - - - Pointer to the profile_tier_level - for the stream. - - - - - - Length of the data available in @profile_tier_level. - - - - - - Sets the level and profile in @caps if it can be determined from -@vis_obj_seq. See gst_codec_utils_mpeg4video_get_level() and -gst_codec_utils_mpeg4video_get_profile() for more details on the -parameters. - - - %TRUE if the level and profile could be set, %FALSE otherwise. - - - - - the #GstCaps to which the level and profile are to be added - - - - Pointer to the visual object - sequence for the stream. - - - - - - Length of the data available in @sps. - - - - - - Converts the level indication in the stream's visual object sequence into -a string. @vis_obj_seq is expected to be the data following the visual -object sequence start code. Only the first byte -(profile_and_level_indication) is used. - - - The level as a const string, or NULL if there is an error. - - - - - Pointer to the visual object - sequence for the stream. - - - - - - Length of the data available in @sps. - - - - - - Converts the profile indication in the stream's visual object sequence into -a string. @vis_obj_seq is expected to be the data following the visual -object sequence start code. Only the first byte -(profile_and_level_indication) is used. - - - The profile as a const string, or NULL if there is an error. - - - - - Pointer to the visual object - sequence for the stream. - - - - - - Length of the data available in @sps. - - - - - - Creates Opus caps from the given parameters. - - - The #GstCaps, or %NULL if the parameters would lead to -invalid Opus caps. - - - - - the sample rate - - - - the number of channels - - - - the channel mapping family - - - - the number of independent streams - - - - the number of stereo streams - - - - the mapping between the streams - - - - - - - - Creates Opus caps from the given OpusHead @header and comment header -@comments. - - - The #GstCaps. - - - - - OpusHead header - - - - Comment header or NULL - - - - - - Creates OpusHead header from the given parameters. - - - The #GstBuffer containing the OpusHead. - - - - - the sample rate - - - - the number of channels - - - - the channel mapping family - - - - the number of independent streams - - - - the number of stereo streams - - - - the mapping between the streams - - - - - - Pre-skip in 48kHz samples or 0 - - - - Output gain or 0 - - - - - - Parses Opus caps and fills the different fields with defaults if possible. - - - %TRUE if parsing was successful, %FALSE otherwise. - - - - - the #GstCaps to parse the data from - - - - the sample rate - - - - the number of channels - - - - the channel mapping family - - - - the number of independent streams - - - - the number of stereo streams - - - - the mapping between the streams - - - - - - - - Parses the OpusHead header. - - - %TRUE if parsing was successful, %FALSE otherwise. - - - - - the OpusHead #GstBuffer - - - - the sample rate - - - - the number of channels - - - - the channel mapping family - - - - the number of independent streams - - - - the number of stereo streams - - - - the mapping between the streams - - - - - - Pre-skip in 48kHz samples or 0 - - - - Output gain or 0 - - - - - - Increments the reference count of @info. - - - - a #GstDiscovererInfo - - - - - Decrements the reference count of @info. - - - - a #GstDiscovererInfo - - - - - Increments the reference count of @info. - - - - a #GstDiscovererStreamInfo - - - - - Decrements the reference count of @info. - - - - a #GstDiscovererStreamInfo - - - - - List all available #GstEncodingTarget for the specified category, or all categories -if @categoryname is %NULL. - - - The list of #GstEncodingTarget - - - - - - - The category, for ex: #GST_ENCODING_CATEGORY_DEVICE. -Can be %NULL. - - - - - - Lists all #GstEncodingTarget categories present on disk. - - - A list -of #GstEncodingTarget categories. - - - - - - - Increases the reference count of the @profile. - - - - a #GstEncodingProfile - - - - - Decreases the reference count of the @profile, possibly freeing the @profile. - - - - a #GstEncodingProfile - - - - - Increases the reference count of the @target. - - - - a #GstEncodingTarget - - - - - Decreases the reference count of the @target, possibly freeing it. - - - - a #GstEncodingTarget - - - - - Requests plugin installation without blocking. Once the plugins have been -installed or installation has failed, @func will be called with the result -of the installation and your provided @user_data pointer. - -This function requires a running GLib/Gtk main loop. If you are not -running a GLib/Gtk main loop, make sure to regularly call -g_main_context_iteration(NULL,FALSE). - -The installer strings that make up @detail are typically obtained by -calling gst_missing_plugin_message_get_installer_detail() on missing-plugin -messages that have been caught on a pipeline's bus or created by the -application via the provided API, such as gst_missing_element_message_new(). - -It is possible to request the installation of multiple missing plugins in -one go (as might be required if there is a demuxer for a certain format -installed but no suitable video decoder and no suitable audio decoder). - - - result code whether an external installer could be started - - - - - NULL-terminated array - of installer string details (see below) - - - - - - a #GstInstallPluginsContext, or NULL - - - - the function to call when the installer program returns - - - - the user data to pass to @func when called, or NULL - - - - - - Checks whether plugin installation (initiated by this application only) -is currently in progress. - - - TRUE if plugin installation is in progress, otherwise FALSE - - - - - Convenience function to return the descriptive string associated -with a status code. This function returns English strings and -should not be used for user messages. It is here only to assist -in debugging. - - - a descriptive string for the status code in @ret - - - - - the return status code - - - - - - Checks whether plugin installation is likely to be supported by the -current environment. This currently only checks whether the helper script -that is to be provided by the distribution or operating system vendor -exists. - - - TRUE if plugin installation is likely to be supported. - - - - - Requests plugin installation and block until the plugins have been -installed or installation has failed. - -This function should almost never be used, it only exists for cases where -a non-GLib main loop is running and the user wants to run it in a separate -thread and marshal the result back asynchronously into the main thread -using the other non-GLib main loop. You should almost always use -gst_install_plugins_async() instead of this function. - - - the result of the installation. - - - - - NULL-terminated array - of installer string details - - - - - - a #GstInstallPluginsContext, or NULL - - - - - - Checks whether @msg is a missing plugins message. - - - %TRUE if @msg is a missing-plugins message, otherwise %FALSE. - - - - - a #GstMessage - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions in -the case where the application knows exactly what kind of plugin it is -missing. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - the (fixed) caps for which a decoder element is needed - - - - - - Creates a missing-plugin message for @element to notify the application -that a decoder element for a particular set of (fixed) caps is missing. -This function is mainly for use in plugins. - - - a new #GstMessage, or NULL on error - - - - - the #GstElement posting the message - - - - the (fixed) caps for which a decoder element is needed - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions in -the case where the application knows exactly what kind of plugin it is -missing. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - the name of the missing element (element factory), - e.g. "videoscale" or "cdparanoiasrc" - - - - - - Creates a missing-plugin message for @element to notify the application -that a certain required element is missing. This function is mainly for -use in plugins. - - - a new #GstMessage, or NULL on error - - - - - the #GstElement posting the message - - - - the name of the missing element (element factory), - e.g. "videoscale" or "cdparanoiasrc" - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions in -the case where the application knows exactly what kind of plugin it is -missing. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - the (fixed) caps for which an encoder element is needed - - - - - - Creates a missing-plugin message for @element to notify the application -that an encoder element for a particular set of (fixed) caps is missing. -This function is mainly for use in plugins. - - - a new #GstMessage, or NULL on error - - - - - the #GstElement posting the message - - - - the (fixed) caps for which an encoder element is needed - - - - - - Returns a localised string describing the missing feature, for use in -error dialogs and the like. Should never return NULL unless @msg is not -a valid missing-plugin message. - -This function is mainly for applications that need a human-readable string -describing a missing plugin, given a previously collected missing-plugin -message - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - a missing-plugin #GstMessage of type #GST_MESSAGE_ELEMENT - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - a missing-plugin #GstMessage of type #GST_MESSAGE_ELEMENT - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions in -the case where the application knows exactly what kind of plugin it is -missing. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - the URI protocol the missing source needs to implement, - e.g. "http" or "mms" - - - - - - Creates a missing-plugin message for @element to notify the application -that a sink element for a particular URI protocol is missing. This -function is mainly for use in plugins. - - - a new #GstMessage, or NULL on error - - - - - the #GstElement posting the message - - - - the URI protocol the missing sink needs to implement, - e.g. "http" or "smb" - - - - - - Returns an opaque string containing all the details about the missing -element to be passed to an external installer called via -gst_install_plugins_async() or gst_install_plugins_sync(). - -This function is mainly for applications that call external plugin -installation mechanisms using one of the two above-mentioned functions in -the case where the application knows exactly what kind of plugin it is -missing. - - - a newly-allocated detail string, or NULL on error. Free string - with g_free() when not needed any longer. - - - - - the URI protocol the missing source needs to implement, - e.g. "http" or "mms" - - - - - - Creates a missing-plugin message for @element to notify the application -that a source element for a particular URI protocol is missing. This -function is mainly for use in plugins. - - - a new #GstMessage, or NULL on error - - - - - the #GstElement posting the message - - - - the URI protocol the missing source needs to implement, - e.g. "http" or "mms" - - - - - - Adds a codec tag describing the format specified by @caps to @taglist. - - - TRUE if a codec tag was added, FALSE otherwise. - - - - - a #GstTagList - - - - a GStreamer codec tag such as #GST_TAG_AUDIO_CODEC, - #GST_TAG_VIDEO_CODEC or #GST_TAG_CODEC. If none is specified, - the function will attempt to detect the appropriate category. - - - - the (fixed) #GstCaps for which a codec tag should be added. - - - - - - Returns a localised (as far as this is possible) string describing the -media format specified in @caps, for use in error dialogs or other messages -to be seen by the user. Should never return NULL unless @caps is invalid. - -Also see the convenience function -gst_pb_utils_add_codec_description_to_tag_list(). - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the (fixed) #GstCaps for which an format description is needed - - - - - - Returns a localised string describing an decoder for the format specified -in @caps, for use in error dialogs or other messages to be seen by the user. -Should never return NULL unless @factory_name or @caps are invalid. - -This function is mainly for internal use, applications would typically -use gst_missing_plugin_message_get_description() to get a description of -a missing feature from a missing-plugin message. - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the (fixed) #GstCaps for which an decoder description is needed - - - - - - Returns a localised string describing the given element, for use in -error dialogs or other messages to be seen by the user. Should never -return NULL unless @factory_name is invalid. - -This function is mainly for internal use, applications would typically -use gst_missing_plugin_message_get_description() to get a description of -a missing feature from a missing-plugin message. - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the name of the element, e.g. "giosrc" - - - - - - Returns a localised string describing an encoder for the format specified -in @caps, for use in error dialogs or other messages to be seen by the user. -Should never return NULL unless @factory_name or @caps are invalid. - -This function is mainly for internal use, applications would typically -use gst_missing_plugin_message_get_description() to get a description of -a missing feature from a missing-plugin message. - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the (fixed) #GstCaps for which an encoder description is needed - - - - - - Returns a localised string describing a sink element handling the protocol -specified in @protocol, for use in error dialogs or other messages to be -seen by the user. Should never return NULL unless @protocol is invalid. - -This function is mainly for internal use, applications would typically -use gst_missing_plugin_message_get_description() to get a description of -a missing feature from a missing-plugin message. - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the protocol the sink element needs to handle, e.g. "http" - - - - - - Returns a localised string describing a source element handling the protocol -specified in @protocol, for use in error dialogs or other messages to be -seen by the user. Should never return NULL unless @protocol is invalid. - -This function is mainly for internal use, applications would typically -use gst_missing_plugin_message_get_description() to get a description of -a missing feature from a missing-plugin message. - - - a newly-allocated description string, or NULL on error. Free - string with g_free() when not needed any longer. - - - - - the protocol the source element needs to handle, e.g. "http" - - - - - - Initialises the base utils support library. This function is not -thread-safe. Applications should call it after calling gst_init(), -plugins should call it from their plugin_init function. - -This function may be called multiple times. It will do nothing if the -library has already been initialised. - - - - - - - Gets the version number of the GStreamer Plugins Base libraries. - - - - - - - pointer to a guint to store the major version number, or %NULL - - - - pointer to a guint to store the minor version number, or %NULL - - - - pointer to a guint to store the micro version number, or %NULL - - - - pointer to a guint to store the nano version number, or %NULL - - - - - - This function returns a string that is useful for describing this version -of GStreamer's gst-plugins-base libraries to the outside world: user agent -strings, logging, about dialogs ... - - - a newly allocated string describing this version of gst-plugins-base - - - - - diff --git a/gir-files/GstPlayer-1.0.gir b/gir-files/GstPlayer-1.0.gir deleted file mode 100644 index df6816df4..000000000 --- a/gir-files/GstPlayer-1.0.gir +++ /dev/null @@ -1,2410 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Creates a new #GstPlayer instance that uses @signal_dispatcher to dispatch -signals to some event loop system, or emits signals directly if NULL is -passed. See gst_player_g_main_context_signal_dispatcher_new(). - -Video is going to be rendered by @video_renderer, or if %NULL is provided -no special video set up will be done and some default handling will be -performed. - - - a new #GstPlayer instance - - - - - GstPlayerVideoRenderer to use - - - - GstPlayerSignalDispatcher to use - - - - - - - - current position update interval in milliseconds - - - - - a #GstPlayer configuration - - - - - - - - %TRUE if accurate seeking is enabled - - - - - a #GstPlayer configuration - - - - - - Return the user agent which has been configured using -gst_player_config_set_user_agent() if any. - - - the configured agent, or %NULL - - - - - a #GstPlayer configuration - - - - - - set interval in milliseconds between two position-updated signals. -pass 0 to stop updating the position. - - - - - - - a #GstPlayer configuration - - - - interval in ms - - - - - - Enable or disable accurate seeking. When enabled, elements will try harder -to seek as accurately as possible to the requested seek position. Generally -it will be slower especially for formats that don't have any indexes or -timestamp markers in the stream. - -If accurate seeking is disabled, elements will seek as close as the request -position without slowing down seeking too much. - -Accurate seeking is disabled by default. - - - - - - - a #GstPlayer configuration - - - - accurate seek or not - - - - - - Set the user agent to pass to the server if @player needs to connect -to a server during playback. This is typically used when playing HTTP -or RTSP streams. - - - - - - - a #GstPlayer configuration - - - - the string to use as user agent - - - - - - - - A #GList of -matching #GstPlayerAudioInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - A #GList of -matching #GstPlayerSubtitleInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - A #GList of -matching #GstPlayerVideoInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - Frees a %NULL terminated array of #GstPlayerVisualization. - - - - - - - a %NULL terminated array of #GstPlayerVisualization to free - - - - - - - - - a %NULL terminated array containing all available - visualizations. Use gst_player_visualizations_free() after - usage. - - - - - - - Retrieve the current value of audio-video-offset property - - - The current value of audio-video-offset in nanoseconds - - - - - #GstPlayer instance - - - - - - Retrieve the current value of the indicated @type. - - - The current value of @type, between [0,1]. In case of - error -1 is returned. - - - - - #GstPlayer instance - - - - #GstPlayerColorBalanceType - - - - - - Get a copy of the current configuration of the player. This configuration -can either be modified and used for the gst_player_set_config() call -or it must be freed after usage. - - - a copy of the current configuration of @player. Use -gst_structure_free() after usage or gst_player_set_config(). - - - - - #GstPlayer instance - - - - - - A Function to get current audio #GstPlayerAudioInfo instance. - - - current audio track. - -The caller should free it with g_object_unref() - - - - - #GstPlayer instance - - - - - - A Function to get current subtitle #GstPlayerSubtitleInfo instance. - - - current subtitle track. - -The caller should free it with g_object_unref() - - - - - #GstPlayer instance - - - - - - A Function to get current video #GstPlayerVideoInfo instance. - - - current video track. - -The caller should free it with g_object_unref() - - - - - #GstPlayer instance - - - - - - - - Name of the currently enabled visualization. - g_free() after usage. - - - - - #GstPlayer instance - - - - - - Retrieves the duration of the media stream that self represents. - - - the duration of the currently-playing media stream, in -nanoseconds. - - - - - #GstPlayer instance - - - - - - A Function to get the current media info #GstPlayerMediaInfo instance. - - - media info instance. - -The caller should free it with g_object_unref() - - - - - #GstPlayer instance - - - - - - Retrieve the current value of the indicated @type. - - - The current value of @type, Default: 0x00000000 "none - - - - - #GstPlayer instance - - - - - - Retrieve the current value of the indicated @type. - - - The current value of @type, Default: -1 "none" - - - - - #GstPlayer instance - - - - - - - - %TRUE if the currently-playing stream is muted. - - - - - #GstPlayer instance - - - - - - - - The internal playbin instance - - - - - #GstPlayer instance - - - - - - - - the absolute position time, in nanoseconds, of the -currently-playing stream. - - - - - #GstPlayer instance - - - - - - - - current playback rate - - - - - #GstPlayer instance - - - - - - current subtitle URI - - - URI of the current external subtitle. - g_free() after usage. - - - - - #GstPlayer instance - - - - - - Retrieve the current value of subtitle-video-offset property - - - The current value of subtitle-video-offset in nanoseconds - - - - - #GstPlayer instance - - - - - - Gets the URI of the currently-playing stream. - - - a string containing the URI of the -currently-playing stream. g_free() after usage. - - - - - #GstPlayer instance - - - - - - Get a snapshot of the currently selected video stream, if any. The format can be -selected with @format and optional configuration is possible with @config -Currently supported settings are: -- width, height of type G_TYPE_INT -- pixel-aspect-ratio of type GST_TYPE_FRACTION - Except for GST_PLAYER_THUMBNAIL_RAW_NATIVE format, if no config is set, pixel-aspect-ratio would be 1/1 - - - Current video snapshot sample or %NULL on failure - - - - - #GstPlayer instance - - - - output format of the video snapshot - - - - Additional configuration - - - - - - Returns the current volume level, as a percentage between 0 and 1. - - - the volume as percentage between 0 and 1. - - - - - #GstPlayer instance - - - - - - Checks whether the @player has color balance support available. - - - %TRUE if @player has color balance support. Otherwise, - %FALSE. - - - - - #GstPlayer instance - - - - - - Pauses the current stream. - - - - - - - #GstPlayer instance - - - - - - Request to play the loaded stream. - - - - - - - #GstPlayer instance - - - - - - Seeks the currently-playing stream to the absolute @position time -in nanoseconds. - - - - - - - #GstPlayer instance - - - - position to seek in nanoseconds - - - - - - - - %TRUE or %FALSE - -Sets the audio track @stream_idex. - - - - - #GstPlayer instance - - - - stream index - - - - - - Enable or disable the current audio track. - - - - - - - #GstPlayer instance - - - - TRUE or FALSE - - - - - - Sets audio-video-offset property by value of @offset - - - - - - - #GstPlayer instance - - - - #gint64 in nanoseconds - - - - - - Sets the current value of the indicated channel @type to the passed -value. - - - - - - - #GstPlayer instance - - - - #GstPlayerColorBalanceType - - - - The new value for the @type, ranged [0,1] - - - - - - Set the configuration of the player. If the player is already configured, and -the configuration haven't change, this function will return %TRUE. If the -player is not in the GST_PLAYER_STATE_STOPPED, this method will return %FALSE -and active configuration will remain. - -@config is a #GstStructure that contains the configuration parameters for -the player. - -This function takes ownership of @config. - - - %TRUE when the configuration could be set. - - - - - #GstPlayer instance - - - - a #GstStructure - - - - - - Sets the current value of the indicated mode @type to the passed -value. - - - - - - - #GstPlayer instance - - - - The new value for the @type - - - - - - Sets the current value of the indicated mode @type to the passed -value. - - - - - - - #GstPlayer instance - - - - The new value for the @type - - - - - - %TRUE if the currently-playing stream should be muted. - - - - - - - #GstPlayer instance - - - - Mute state the should be set - - - - - - Playback at specified rate - - - - - - - #GstPlayer instance - - - - playback rate - - - - - - - - %TRUE or %FALSE - -Sets the subtitle stack @stream_index. - - - - - #GstPlayer instance - - - - stream index - - - - - - Enable or disable the current subtitle track. - - - - - - - #GstPlayer instance - - - - TRUE or FALSE - - - - - - Sets the external subtitle URI. This should be combined with a call to -gst_player_set_subtitle_track_enabled(@player, TRUE) so the subtitles are actually -rendered. - - - - - - - #GstPlayer instance - - - - subtitle URI - - - - - - Sets subtitle-video-offset property by value of @offset - - - - - - - #GstPlayer instance - - - - #gint64 in nanoseconds - - - - - - Sets the next URI to play. - - - - - - - #GstPlayer instance - - - - next URI to play. - - - - - - - - %TRUE or %FALSE - -Sets the video track @stream_index. - - - - - #GstPlayer instance - - - - stream index - - - - - - Enable or disable the current video track. - - - - - - - #GstPlayer instance - - - - TRUE or FALSE - - - - - - - - %TRUE if the visualizations was set correctly. Otherwise, -%FALSE. - - - - - #GstPlayer instance - - - - visualization element obtained from -#gst_player_visualizations_get() - - - - - - Enable or disable the visualization. - - - - - - - #GstPlayer instance - - - - TRUE or FALSE - - - - - - Sets the volume level of the stream as a percentage between 0 and 1. - - - - - - - #GstPlayer instance - - - - the new volume level, as a percentage between 0 and 1 - - - - - - Stops playing the current stream and resets to the first position -in the stream. - - - - - - - #GstPlayer instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstPlayerStreamInfo specific to audio streams. - - - - - the audio bitrate in #GstPlayerAudioInfo. - - - - - a #GstPlayerAudioInfo - - - - - - - - the number of audio channels in #GstPlayerAudioInfo. - - - - - a #GstPlayerAudioInfo - - - - - - - - the language of the stream, or NULL if unknown. - - - - - a #GstPlayerAudioInfo - - - - - - - - the audio maximum bitrate in #GstPlayerAudioInfo. - - - - - a #GstPlayerAudioInfo - - - - - - - - the audio sample rate in #GstPlayerAudioInfo. - - - - - a #GstPlayerAudioInfo - - - - - - - - - - - - - - hue or color balance. - - - brightness or black level. - - - color saturation or chroma -gain. - - - contrast or luma gain. - - - Gets a string representing the given color balance type. - - - a string with the name of the color - balance type. - - - - - a #GstPlayerColorBalanceType - - - - - - - - generic error. - - - Gets a string representing the given error. - - - a string with the given error. - - - - - a #GstPlayerError - - - - - - - - - - - - - - - Creates a new GstPlayerSignalDispatcher that uses @application_context, -or the thread default one if %NULL is used. See gst_player_new(). - - - the new GstPlayerSignalDispatcher - - - - - GMainContext to use or %NULL - - - - - - - - - - - - - Structure containing the media information of a URI. - - - - - A #GList of -matching #GstPlayerAudioInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - the container format. - - - - - a #GstPlayerMediaInfo - - - - - - - - duration of the media. - - - - - a #GstPlayerMediaInfo - - - - - - Function to get the image (or preview-image) stored in taglist. -Application can use `gst_sample_*_()` API's to get caps, buffer etc. - - - GstSample or NULL. - - - - - a #GstPlayerMediaInfo - - - - - - - - number of audio streams. - - - - - a #GstPlayerMediaInfo - - - - - - - - number of total streams. - - - - - a #GstPlayerMediaInfo - - - - - - - - number of subtitle streams. - - - - - a #GstPlayerMediaInfo - - - - - - - - number of video streams. - - - - - a #GstPlayerMediaInfo - - - - - - - - A #GList of -matching #GstPlayerStreamInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - A #GList of -matching #GstPlayerSubtitleInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - the tags contained in media info. - - - - - a #GstPlayerMediaInfo - - - - - - - - the media title. - - - - - a #GstPlayerMediaInfo - - - - - - - - the URI associated with #GstPlayerMediaInfo. - - - - - a #GstPlayerMediaInfo - - - - - - - - A #GList of -matching #GstPlayerVideoInfo. - - - - - - - a #GstPlayerMediaInfo - - - - - - - - %TRUE if the media is live. - - - - - a #GstPlayerMediaInfo - - - - - - - - %TRUE if the media is seekable. - - - - - a #GstPlayerMediaInfo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the player is stopped. - - - the player is buffering. - - - the player is paused. - - - the player is currently playing a -stream. - - - Gets a string representing the given state. - - - a string with the name of the state. - - - - - a #GstPlayerState - - - - - - - Base structure for information concerning a media stream. Depending on -the stream type, one can find more media-specific information in -#GstPlayerVideoInfo, #GstPlayerAudioInfo, #GstPlayerSubtitleInfo. - - - - - the #GstCaps of the stream. - - - - - a #GstPlayerStreamInfo - - - - - - A string describing codec used in #GstPlayerStreamInfo. - - - codec string or NULL on unknown. - - - - - a #GstPlayerStreamInfo - - - - - - Function to get stream index from #GstPlayerStreamInfo instance. - - - the stream index of this stream. - - - - - a #GstPlayerStreamInfo - - - - - - Function to return human readable name for the stream type -of the given @info (ex: "audio", "video", "subtitle") - - - a human readable name - - - - - a #GstPlayerStreamInfo - - - - - - - - the tags contained in this stream. - - - - - a #GstPlayerStreamInfo - - - - - - - - - - #GstPlayerStreamInfo specific to subtitle streams. - - - - - the language of the stream, or NULL if unknown. - - - - - a #GstPlayerSubtitleInfo - - - - - - - - - - #GstPlayerStreamInfo specific to video streams. - - - - - the current bitrate of video in #GstPlayerVideoInfo. - - - - - a #GstPlayerVideoInfo - - - - - - - - - - - - a #GstPlayerVideoInfo - - - - Numerator of frame rate - - - - Denominator of frame rate - - - - - - - - the height of video in #GstPlayerVideoInfo. - - - - - a #GstPlayerVideoInfo - - - - - - - - the maximum bitrate of video in #GstPlayerVideoInfo. - - - - - a #GstPlayerVideoInfo - - - - - - Returns the pixel aspect ratio in @par_n and @par_d - - - - - - - a #GstPlayerVideoInfo - - - - numerator - - - - denominator - - - - - - - - the width of video in #GstPlayerVideoInfo. - - - - - a #GstPlayerVideoInfo - - - - - - - - - - - - - - - - - - - Window handle to use or %NULL - - - - - - - - - - - - Window handle to use or %NULL - - - - the custom video_sink element to be set for the video renderer - - - - - - Tell an overlay that it has been exposed. This will redraw the current frame -in the drawable even if the pipeline is PAUSED. - - - - - - - a #GstPlayerVideoOverlayVideoRenderer instance. - - - - - - Return the currently configured render rectangle. See gst_player_video_overlay_video_renderer_set_render_rectangle() -for details. - - - - - - - a #GstPlayerVideoOverlayVideoRenderer instance - - - - the horizontal offset of the render area inside the window - - - - the vertical offset of the render area inside the window - - - - the width of the render area inside the window - - - - the height of the render area inside the window - - - - - - - - The currently set, platform specific window -handle - - - - - #GstPlayerVideoRenderer instance - - - - - - Configure a subregion as a video target within the window set by -gst_player_video_overlay_video_renderer_set_window_handle(). If this is not -used or not supported the video will fill the area of the window set as the -overlay to 100%. By specifying the rectangle, the video can be overlaid to -a specific region of that window only. After setting the new rectangle one -should call gst_player_video_overlay_video_renderer_expose() to force a -redraw. To unset the region pass -1 for the @width and @height parameters. - -This method is needed for non fullscreen video overlay in UI toolkits that -do not support subwindows. - - - - - - - a #GstPlayerVideoOverlayVideoRenderer instance - - - - the horizontal offset of the render area inside the window - - - - the vertical offset of the render area inside the window - - - - the width of the render area inside the window - - - - the height of the render area inside the window - - - - - - Sets the platform specific window handle into which the video -should be rendered - - - - - - - #GstPlayerVideoRenderer instance - - - - handle referencing to the platform specific window - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A #GstPlayerVisualization descriptor. - - - name of the visualization. - - - - description of the visualization. - - - - Makes a copy of the #GstPlayerVisualization. The result must be -freed using gst_player_visualization_free(). - - - an allocated copy of @vis. - - - - - #GstPlayerVisualization instance - - - - - - Frees a #GstPlayerVisualization. - - - - - - - #GstPlayerVisualization instance - - - - - - - Gets a string representing the given color balance type. - - - a string with the name of the color - balance type. - - - - - a #GstPlayerColorBalanceType - - - - - - Gets a string representing the given error. - - - a string with the given error. - - - - - a #GstPlayerError - - - - - - - - - - - Gets a string representing the given state. - - - a string with the name of the state. - - - - - a #GstPlayerState - - - - - - diff --git a/gir-files/GstRtp-1.0.gir b/gir-files/GstRtp-1.0.gir deleted file mode 100644 index f9c24e2a9..000000000 --- a/gir-files/GstRtp-1.0.gir +++ /dev/null @@ -1,5548 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Note: The API in this module is not yet declared stable. - -The GstRTPCBuffer helper functions makes it easy to parse and create regular -#GstBuffer objects that contain compound RTCP packets. These buffers are typically -of 'application/x-rtcp' #GstCaps. - -An RTCP buffer consists of 1 or more #GstRTCPPacket structures that you can -retrieve with gst_rtcp_buffer_get_first_packet(). #GstRTCPPacket acts as a pointer -into the RTCP buffer; you can move to the next packet with -gst_rtcp_packet_move_to_next(). - - - - - - - - - Add a new packet of @type to @rtcp. @packet will point to the newly created -packet. - - - %TRUE if the packet could be created. This function returns %FALSE -if the max mtu is exceeded for the buffer. - - - - - a valid RTCP buffer - - - - the #GstRTCPType of the new packet - - - - pointer to new packet - - - - - - Initialize a new #GstRTCPPacket pointer that points to the first packet in -@rtcp. - - - TRUE if the packet existed in @rtcp. - - - - - a valid RTCP buffer - - - - a #GstRTCPPacket - - - - - - Get the number of RTCP packets in @rtcp. - - - the number of RTCP packets in @rtcp. - - - - - a valid RTCP buffer - - - - - - Finish @rtcp after being constructed. This function is usually called -after gst_rtcp_buffer_map() and after adding the RTCP items to the new buffer. - -The function adjusts the size of @rtcp with the total length of all the -added packets. - - - - - - - a buffer with an RTCP packet - - - - - - Open @buffer for reading or writing, depending on @flags. The resulting RTCP -buffer state is stored in @rtcp. - - - - - - - a buffer with an RTCP packet - - - - flags for the mapping - - - - resulting #GstRTCPBuffer - - - - - - Create a new buffer for constructing RTCP packets. The packet will have a -maximum size of @mtu. - - - A newly allocated buffer. - - - - - the maximum mtu size. - - - - - - Create a new buffer and set the data to a copy of @len -bytes of @data and the size to @len. The data will be freed when the buffer -is freed. - - - A newly allocated buffer with a copy of @data and of size @len. - - - - - data for the new buffer - - - - - - the length of data - - - - - - Create a new buffer and set the data and size of the buffer to @data and @len -respectively. @data will be freed when the buffer is unreffed, so this -function transfers ownership of @data to the new buffer. - - - A newly allocated buffer with @data and of size @len. - - - - - data for the new buffer - - - - - - the length of data - - - - - - Check if the data pointed to by @buffer is a valid RTCP packet using -gst_rtcp_buffer_validate_data(). - - - TRUE if @buffer is a valid RTCP packet. - - - - - the buffer to validate - - - - - - Check if the @data and @size point to the data of a valid compound, -non-reduced size RTCP packet. -Use this function to validate a packet before using the other functions in -this module. - - - TRUE if the data points to a valid RTCP packet. - - - - - the data to validate - - - - - - the length of @data to validate - - - - - - Check if the @data and @size point to the data of a valid RTCP packet. -Use this function to validate a packet before using the other functions in -this module. - -This function is updated to support reduced size rtcp packets according to -RFC 5506 and will validate full compound RTCP packets as well as reduced -size RTCP packets. - - - TRUE if the data points to a valid RTCP packet. - - - - - the data to validate - - - - - - the length of @data to validate - - - - - - Check if the data pointed to by @buffer is a valid RTCP packet using -gst_rtcp_buffer_validate_reduced(). - - - TRUE if @buffer is a valid RTCP packet. - - - - - the buffer to validate - - - - - - - Different types of feedback messages. - - Invalid type - - - Generic NACK - - - Temporary Maximum Media Stream Bit Rate Request - - - Temporary Maximum Media Stream Bit Rate - Notification - - - Request an SR packet for early - synchronization - - - - - Picture Loss Indication - - - Slice Loss Indication - - - Reference Picture Selection Indication - - - Application layer Feedback - - - Full Intra Request Command - - - Temporal-Spatial Trade-off Request - - - Temporal-Spatial Trade-off Notification - - - Video Back Channel Message - - - - Data structure that points to a packet at @offset in @buffer. -The size of the structure is made public to allow stack allocations. - - - pointer to RTCP buffer - - - - offset of packet in buffer data - - - - - - - - - - - - - - - - - - - - - - - - - Add profile-specific extension @data to @packet. If @packet already -contains profile-specific extension @data will be appended to the existing -extension. - - - %TRUE if the profile specific extension data was added. - - - - - a valid SR or RR #GstRTCPPacket - - - - profile-specific data - - - - - - length of the profile-specific data in bytes - - - - - - Add a new report block to @packet with the given values. - - - %TRUE if the packet was created. This function can return %FALSE if -the max MTU is exceeded or the number of report blocks is greater than -#GST_RTCP_MAX_RB_COUNT. - - - - - a valid SR or RR #GstRTCPPacket - - - - data source being reported - - - - fraction lost since last SR/RR - - - - the cumululative number of packets lost - - - - the extended last sequence number received - - - - the interarrival jitter - - - - the last SR packet from this source - - - - the delay since last SR packet - - - - - - Get the application-dependent data attached to a RTPFB or PSFB @packet. - - - A pointer to the data - - - - - a valid APP #GstRTCPPacket - - - - - - Get the length of the application-dependent data attached to an APP -@packet. - - - The length of data in 32-bit words. - - - - - a valid APP #GstRTCPPacket - - - - - - Get the name field of the APP @packet. - - - The 4-byte name field, not zero-terminated. - - - - - a valid APP #GstRTCPPacket - - - - - - Get the SSRC/CSRC field of the APP @packet. - - - The SSRC/CSRC. - - - - - a valid APP #GstRTCPPacket - - - - - - Get the subtype field of the APP @packet. - - - The subtype. - - - - - a valid APP #GstRTCPPacket - - - - - - Set the length of the application-dependent data attached to an APP -@packet. - - - %TRUE if there was enough space in the packet to add this much -data. - - - - - a valid APP #GstRTCPPacket - - - - Length of the data in 32-bit words - - - - - - Set the name field of the APP @packet. - - - - - - - a valid APP #GstRTCPPacket - - - - 4-byte ASCII name - - - - - - Set the SSRC/CSRC field of the APP @packet. - - - - - - - a valid APP #GstRTCPPacket - - - - SSRC/CSRC of the packet - - - - - - Set the subtype field of the APP @packet. - - - - - - - a valid APP #GstRTCPPacket - - - - subtype of the packet - - - - - - Add @ssrc to the BYE @packet. - - - %TRUE if the ssrc was added. This function can return %FALSE if -the max MTU is exceeded or the number of sources blocks is greater than -#GST_RTCP_MAX_BYE_SSRC_COUNT. - - - - - a valid BYE #GstRTCPPacket - - - - an SSRC to add - - - - - - Adds @len SSRCs in @ssrc to BYE @packet. - - - %TRUE if the all the SSRCs were added. This function can return %FALSE if -the max MTU is exceeded or the number of sources blocks is greater than -#GST_RTCP_MAX_BYE_SSRC_COUNT. - - - - - a valid BYE #GstRTCPPacket - - - - an array of SSRCs to add - - - - - - number of elements in @ssrc - - - - - - Get the @nth SSRC of the BYE @packet. - - - The @nth SSRC of @packet. - - - - - a valid BYE #GstRTCPPacket - - - - the nth SSRC to get - - - - - - Get the reason in @packet. - - - The reason for the BYE @packet or NULL if the packet did not contain -a reason string. The string must be freed with g_free() after usage. - - - - - a valid BYE #GstRTCPPacket - - - - - - Get the length of the reason string. - - - The length of the reason string or 0 when there is no reason string -present. - - - - - a valid BYE #GstRTCPPacket - - - - - - Get the number of SSRC fields in @packet. - - - The number of SSRC fields in @packet. - - - - - a valid BYE #GstRTCPPacket - - - - - - Set the reason string to @reason in @packet. - - - TRUE if the string could be set. - - - - - a valid BYE #GstRTCPPacket - - - - a reason string - - - - - - The profile-specific extension data is copied into a new allocated -memory area @data. This must be freed with g_free() after usage. - - - %TRUE if there was valid data. - - - - - a valid SR or RR #GstRTCPPacket - - - - result profile-specific data - - - - - - length of the profile-specific extension data - - - - - - Get the Feedback Control Information attached to a RTPFB or PSFB @packet. - - - a pointer to the FCI - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - - - Get the length of the Feedback Control Information attached to a -RTPFB or PSFB @packet. - - - The length of the FCI in 32-bit words. - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - - - Get the media SSRC field of the RTPFB or PSFB @packet. - - - the media SSRC. - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - - - Get the sender SSRC field of the RTPFB or PSFB @packet. - - - the sender SSRC. - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - - - Get the feedback message type of the FB @packet. - - - The feedback message type. - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - - - Set the length of the Feedback Control Information attached to a -RTPFB or PSFB @packet. - - - %TRUE if there was enough space in the packet to add this much FCI - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - Length of the FCI in 32-bit words - - - - - - Set the media SSRC field of the RTPFB or PSFB @packet. - - - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - a media SSRC - - - - - - Set the sender SSRC field of the RTPFB or PSFB @packet. - - - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - a sender SSRC - - - - - - Set the feedback message type of the FB @packet. - - - - - - - a valid RTPFB or PSFB #GstRTCPPacket - - - - the #GstRTCPFBType to set - - - - - - Get the count field in @packet. - - - The count field in @packet or -1 if @packet does not point to a -valid packet. - - - - - a valid #GstRTCPPacket - - - - - - Get the length field of @packet. This is the length of the packet in -32-bit words minus one. - - - The length field of @packet. - - - - - a valid #GstRTCPPacket - - - - - - Get the packet padding of the packet pointed to by @packet. - - - If the packet has the padding bit set. - - - - - a valid #GstRTCPPacket - - - - - - - - %TRUE if there was valid data. - - - - - a valid SR or RR #GstRTCPPacket - - - - result profile-specific data - - - - - - result length of the profile-specific data - - - - - - - - The number of 32-bit words containing profile-specific extension - data from @packet. - - - - - a valid SR or RR #GstRTCPPacket - - - - - - Parse the values of the @nth report block in @packet and store the result in -the values. - - - - - - - a valid SR or RR #GstRTCPPacket - - - - the nth report block in @packet - - - - result for data source being reported - - - - result for fraction lost since last SR/RR - - - - result for the cumululative number of packets lost - - - - result for the extended last sequence number received - - - - result for the interarrival jitter - - - - result for the last SR packet from this source - - - - result for the delay since last SR packet - - - - - - Get the number of report blocks in @packet. - - - The number of report blocks in @packet. - - - - - a valid SR or RR #GstRTCPPacket - - - - - - Get the packet type of the packet pointed to by @packet. - - - The packet type or GST_RTCP_TYPE_INVALID when @packet is not -pointing to a valid packet. - - - - - a valid #GstRTCPPacket - - - - - - Move the packet pointer @packet to the next packet in the payload. -Use gst_rtcp_buffer_get_first_packet() to initialize @packet. - - - TRUE if @packet is pointing to a valid packet after calling this -function. - - - - - a #GstRTCPPacket - - - - - - Removes the packet pointed to by @packet and moves pointer to the next one - - - TRUE if @packet is pointing to a valid packet after calling this -function. - - - - - a #GstRTCPPacket - - - - - - Get the ssrc field of the RR @packet. - - - the ssrc. - - - - - a valid RR #GstRTCPPacket - - - - - - Set the ssrc field of the RR @packet. - - - - - - - a valid RR #GstRTCPPacket - - - - the SSRC to set - - - - - - Add a new SDES entry to the current item in @packet. - - - %TRUE if the item could be added, %FALSE if the MTU has been -reached. - - - - - a valid SDES #GstRTCPPacket - - - - the #GstRTCPSDESType of the SDES entry - - - - the data length - - - - the data - - - - - - - - Add a new SDES item for @ssrc to @packet. - - - %TRUE if the item could be added, %FALSE if the maximum amount of -items has been exceeded for the SDES packet or the MTU has been reached. - - - - - a valid SDES #GstRTCPPacket - - - - the SSRC of the new item to add - - - - - - This function is like gst_rtcp_packet_sdes_get_entry() but it returns a -null-terminated copy of the data instead. use g_free() after usage. - - - %TRUE if there was valid data. - - - - - a valid SDES #GstRTCPPacket - - - - result of the entry type - - - - result length of the entry data - - - - result entry data - - - - - - - - Move to the first SDES entry in the current item. - - - %TRUE if there was a first entry. - - - - - a valid SDES #GstRTCPPacket - - - - - - Move to the first SDES item in @packet. - - - TRUE if there was a first item. - - - - - a valid SDES #GstRTCPPacket - - - - - - Get the data of the current SDES item entry. @type (when not NULL) will -contain the type of the entry. @data (when not NULL) will point to @len -bytes. - -When @type refers to a text item, @data will point to a UTF8 string. Note -that this UTF8 string is NOT null-terminated. Use -gst_rtcp_packet_sdes_copy_entry() to get a null-terminated copy of the entry. - - - %TRUE if there was valid data. - - - - - a valid SDES #GstRTCPPacket - - - - result of the entry type - - - - result length of the entry data - - - - result entry data - - - - - - - - Get the number of items in the SDES packet @packet. - - - The number of items in @packet. - - - - - a valid SDES #GstRTCPPacket - - - - - - Get the SSRC of the current SDES item. - - - the SSRC of the current item. - - - - - a valid SDES #GstRTCPPacket - - - - - - Move to the next SDES entry in the current item. - - - %TRUE if there was a next entry. - - - - - a valid SDES #GstRTCPPacket - - - - - - Move to the next SDES item in @packet. - - - TRUE if there was a next item. - - - - - a valid SDES #GstRTCPPacket - - - - - - Set the @nth new report block in @packet with the given values. - -Note: Not implemented. - - - - - - - a valid SR or RR #GstRTCPPacket - - - - the nth report block to set - - - - data source being reported - - - - fraction lost since last SR/RR - - - - the cumululative number of packets lost - - - - the extended last sequence number received - - - - the interarrival jitter - - - - the last SR packet from this source - - - - the delay since last SR packet - - - - - - Parse the SR sender info and store the values. - - - - - - - a valid SR #GstRTCPPacket - - - - result SSRC - - - - result NTP time - - - - result RTP time - - - - result packet count - - - - result octet count - - - - - - Set the given values in the SR packet @packet. - - - - - - - a valid SR #GstRTCPPacket - - - - the SSRC - - - - the NTP time - - - - the RTP time - - - - the packet count - - - - the octet count - - - - - - Move to the first extended report block in XR @packet. - - - TRUE if there was a first extended report block. - - - - - a valid XR #GstRTCPPacket - - - - - - - - The number of 32-bit words containing type-specific block - data from @packet. - - - - - a valid XR #GstRTCPPacket - - - - - - Get the extended report block type of the XR @packet. - - - The extended report block type. - - - - - a valid XR #GstRTCPPacket - - - - - - Parse the extended report block for DLRR report block type. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has DLRR Report Block. - - - - the index of sub-block to retrieve. - - - - the SSRC of the receiver. - - - - the last receiver reference timestamp of @ssrc. - - - - the delay since @last_rr. - - - - - - Retrieve the packet receipt time of @seq which ranges in [begin_seq, end_seq). - - - %TRUE if the report block returns the receipt time correctly. - - - - - a valid XR #GstRTCPPacket which has the Packet Recept Times Report Block. - - - - the sequence to retrieve the time. - - - - the packet receipt time of @seq. - - - - - - Parse the Packet Recept Times Report Block from a XR @packet - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has a Packet Receipt Times Report Block - - - - the SSRC of the RTP data packet source being reported upon by this report block. - - - - the amount of thinning performed on the sequence number space. - - - - the first sequence number that this block reports on. - - - - the last sequence number that this block reports on plus one. - - - - - - Parse the extended report block for Loss RLE and Duplicated LRE block type. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which is Loss RLE or Duplicate RLE report. - - - - the SSRC of the RTP data packet source being reported upon by this report block. - - - - the amount of thinning performed on the sequence number space. - - - - the first sequence number that this block reports on. - - - - the last sequence number that this block reports on plus one. - - - - the number of chunks calculated by block length. - - - - - - Retrieve actual chunk data. - - - %TRUE if the report block returns chunk correctly. - - - - - a valid XR #GstRTCPPacket which is Loss RLE or Duplicate RLE report. - - - - the index of chunk to retrieve. - - - - the @nth chunk. - - - - - - - - %TRUE if the report block returns the reference time correctly. - - - - - a valid XR #GstRTCPPacket which has the Receiver Reference Time. - - - - NTP timestamp - - - - - - Get the ssrc field of the XR @packet. - - - the ssrc. - - - - - a valid XR #GstRTCPPacket - - - - - - Extract a basic information from static summary report block of XR @packet. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has Statics Summary Report Block. - - - - the SSRC of the source. - - - - the first sequence number that this block reports on. - - - - the last sequence number that this block reports on plus one. - - - - - - Extract jitter information from the statistics summary. If the jitter flag in -a block header is set as zero, all of jitters will be zero. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has Statics Summary Report Block. - - - - the minimum relative transit time between two sequences. - - - - the maximum relative transit time between two sequences. - - - - the mean relative transit time between two sequences. - - - - the standard deviation of the relative transit time between two sequences. - - - - - - Get the number of lost or duplicate packets. If the flag in a block header -is set as zero, @lost_packets or @dup_packets will be zero. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has Statics Summary Report Block. - - - - the number of lost packets between begin_seq and end_seq. - - - - the number of duplicate packets between begin_seq and end_seq. - - - - - - Extract the value of ttl for ipv4, or hop limit for ipv6. - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has Statics Summary Report Block. - - - - the flag to indicate that the return values are ipv4 ttl or ipv6 hop limits. - - - - the minimum TTL or Hop Limit value of data packets between two sequences. - - - - the maximum TTL or Hop Limit value of data packets between two sequences. - - - - the mean TTL or Hop Limit value of data packets between two sequences. - - - - the standard deviation of the TTL or Hop Limit value of data packets between two sequences. - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the fraction of RTP data packets within burst periods. - - - - the fraction of RTP data packets within inter-burst gaps. - - - - the mean duration(ms) of the burst periods. - - - - the mean duration(ms) of the gap periods. - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the gap threshold. - - - - the receiver configuration byte. - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the most recently calculated round trip time between RTP interfaces(ms) - - - - the most recently estimated end system delay(ms) - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the current nominal jitter buffer delay(ms) - - - - the current maximum jitter buffer delay(ms) - - - - the absolute maximum delay(ms) - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the SSRC of source - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the fraction of RTP data packets from the source lost. - - - - the fraction of RTP data packets from the source that have been discarded. - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the R factor is a voice quality metric describing the segment of the call. - - - - the external R factor is a voice quality metric. - - - - the estimated mean opinion score for listening quality. - - - - the estimated mean opinion score for conversational quality. - - - - - - - - %TRUE if the report block is correctly parsed. - - - - - a valid XR #GstRTCPPacket which has VoIP Metrics Report Block. - - - - the ratio of the signal level to a 0 dBm reference. - - - - the ratio of the silent period background noise level to a 0 dBm reference. - - - - the residual echo return loss value. - - - - the gap threshold. - - - - - - Move to the next extended report block in XR @packet. - - - TRUE if there was a next extended report block. - - - - - a valid XR #GstRTCPPacket - - - - - - - Different types of SDES content. - - Invalid SDES entry - - - End of SDES list - - - Canonical name - - - User name - - - User's electronic mail address - - - User's phone number - - - Geographic user location - - - Name of application or tool - - - Notice about the source - - - Private extensions - - - - Different RTCP packet types. - - Invalid type - - - Sender report - - - Receiver report - - - Source description - - - Goodbye - - - Application defined - - - Transport layer feedback. - - - Payload-specific feedback. - - - Extended report. - - - - Types of RTCP Extended Reports, those are defined in RFC 3611 and other RFCs -according to the [IANA registry](https://www.iana.org/assignments/rtcp-xr-block-types/rtcp-xr-block-types.xhtml). - - Invalid XR Report Block - - - Loss RLE Report Block - - - Duplicate RLE Report Block - - - Packet Receipt Times Report Block - - - Receiver Reference Time Report Block - - - Delay since the last Receiver Report - - - Statistics Summary Report Block - - - VoIP Metrics Report Block - - - - The maximum amount of SSRCs in a BYE packet. - - - - - The maximum amount of Receiver report blocks in RR and SR messages. - - - - - The maximum text length for an SDES item. - - - - - The maximum amount of SDES items. - - - - - Mask for version, padding bit and packet type pair allowing reduced size -packets, basically it accepts other types than RR and SR - - - - - Mask for version, padding bit and packet type pair - - - - - Valid value for the first two bytes of an RTCP packet after applying -#GST_RTCP_VALID_MASK to them. - - - - - The supported RTCP version 2. - - - - - Provides a base class for audio RTP payloaders for frame or sample based -audio codecs (constant bitrate) - -This class derives from GstRTPBasePayload. It can be used for payloading -audio codecs. It will only work with constant bitrate codecs. It supports -both frame based and sample based codecs. It takes care of packing up the -audio data into RTP packets and filling up the headers accordingly. The -payloading is done based on the maximum MTU (mtu) and the maximum time per -packet (max-ptime). The general idea is to divide large data buffers into -smaller RTP packets. The RTP packet size is the minimum of either the MTU, -max-ptime (if set) or available data. The RTP packet size is always larger or -equal to min-ptime (if set). If min-ptime is not set, any residual data is -sent in a last RTP packet. In the case of frame based codecs, the resulting -RTP packets always contain full frames. - -## Usage - -To use this base class, your child element needs to call either -gst_rtp_base_audio_payload_set_frame_based() or -gst_rtp_base_audio_payload_set_sample_based(). This is usually done in the -element's `_init()` function. Then, the child element must call either -gst_rtp_base_audio_payload_set_frame_options(), -gst_rtp_base_audio_payload_set_sample_options() or -gst_rtp_base_audio_payload_set_samplebits_options. Since -GstRTPBaseAudioPayload derives from GstRTPBasePayload, the child element -must set any variables or call/override any functions required by that base -class. The child element does not need to override any other functions -specific to GstRTPBaseAudioPayload. - - - Create an RTP buffer and store @payload_len bytes of the adapter as the -payload. Set the timestamp on the new buffer to @timestamp before pushing -the buffer downstream. - -If @payload_len is -1, all pending bytes will be flushed. If @timestamp is --1, the timestamp will be calculated automatically. - - - a #GstFlowReturn - - - - - a #GstRTPBasePayload - - - - length of payload - - - - a #GstClockTime - - - - - - Gets the internal adapter used by the depayloader. - - - a #GstAdapter. - - - - - a #GstRTPBaseAudioPayload - - - - - - Create an RTP buffer and store @payload_len bytes of @data as the -payload. Set the timestamp on the new buffer to @timestamp before pushing -the buffer downstream. - - - a #GstFlowReturn - - - - - a #GstRTPBasePayload - - - - data to set as payload - - - - - - length of payload - - - - a #GstClockTime - - - - - - Tells #GstRTPBaseAudioPayload that the child element is for a frame based -audio codec - - - - - - - a pointer to the element. - - - - - - Sets the options for frame based audio codecs. - - - - - - - a pointer to the element. - - - - The duraction of an audio frame in milliseconds. - - - - The size of an audio frame in bytes. - - - - - - Tells #GstRTPBaseAudioPayload that the child element is for a sample based -audio codec - - - - - - - a pointer to the element. - - - - - - Sets the options for sample based audio codecs. - - - - - - - a pointer to the element. - - - - Size per sample in bytes. - - - - - - Sets the options for sample based audio codecs. - - - - - - - a pointer to the element. - - - - Size per sample in bits. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for audio RTP payloader. - - - the parent class - - - - - - - - - - - - - Provides a base class for RTP depayloaders - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Queries whether #GstRTPSourceMeta will be added to depayloaded buffers. - - - %TRUE if source-info is enabled. - - - - - a #GstRTPBaseDepayload - - - - - - Push @out_buf to the peer of @filter. This function takes ownership of -@out_buf. - -This function will by default apply the last incoming timestamp on -the outgoing buffer when it didn't have a timestamp already. - - - a #GstFlowReturn. - - - - - a #GstRTPBaseDepayload - - - - a #GstBuffer - - - - - - Push @out_list to the peer of @filter. This function takes ownership of -@out_list. - - - a #GstFlowReturn. - - - - - a #GstRTPBaseDepayload - - - - a #GstBufferList - - - - - - Enable or disable adding #GstRTPSourceMeta to depayloaded buffers. - - - - - - - a #GstRTPBaseDepayload - - - - whether to add meta about RTP sources to buffer - - - - - - Max seqnum reorder before the sender is assumed to have restarted. - -When max-reorder is set to 0 all reordered/duplicate packets are -considered coming from a restarted sender. - - - - Add RTP source information found in RTP header as meta to output buffer. - - - - Various depayloader statistics retrieved atomically (and are therefore -synchroized with each other). This property return a GstStructure named -application/x-rtp-depayload-stats containing the following fields relating to -the last processed buffer and current state of the stream being depayloaded: - - * `clock-rate`: #G_TYPE_UINT, clock-rate of the stream - * `npt-start`: #G_TYPE_UINT64, time of playback start - * `npt-stop`: #G_TYPE_UINT64, time of playback stop - * `play-speed`: #G_TYPE_DOUBLE, the playback speed - * `play-scale`: #G_TYPE_DOUBLE, the playback scale - * `running-time-dts`: #G_TYPE_UINT64, the last running-time of the - last DTS - * `running-time-pts`: #G_TYPE_UINT64, the last running-time of the - last PTS - * `seqnum`: #G_TYPE_UINT, the last seen seqnum - * `timestamp`: #G_TYPE_UINT, the last seen RTP timestamp - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for RTP depayloaders. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Provides a base class for RTP payloaders - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Allocate a new #GstBuffer with enough data to hold an RTP packet with -minimum @csrc_count CSRCs, a payload length of @payload_len and padding of -@pad_len. If @payload has #GstRTPBasePayload:source-info %TRUE additional -CSRCs may be allocated and filled with RTP source information. - - - A newly allocated buffer that can hold an RTP packet with given -parameters. - - - - - a #GstRTPBasePayload - - - - the length of the payload - - - - the amount of padding - - - - the minimum number of CSRC entries - - - - - - Count the total number of RTP sources found in the meta of @buffer, which -will be automically added by gst_rtp_base_payload_allocate_output_buffer(). -If #GstRTPBasePayload:source-info is %FALSE the count will be 0. - - - The number of sources. - - - - - a #GstRTPBasePayload - - - - a #GstBuffer, typically the buffer to payload - - - - - - Check if the packet with @size and @duration would exceed the configured -maximum size. - - - %TRUE if the packet of @size and @duration would exceed the -configured MTU or max_ptime. - - - - - a #GstRTPBasePayload - - - - the size of the packet - - - - the duration of the packet - - - - - - Queries whether the payloader will add contributing sources (CSRCs) to the -RTP header from #GstRTPSourceMeta. - - - %TRUE if source-info is enabled. - - - - - a #GstRTPBasePayload - - - - - - Push @buffer to the peer element of the payloader. The SSRC, payload type, -seqnum and timestamp of the RTP buffer will be updated first. - -This function takes ownership of @buffer. - - - a #GstFlowReturn. - - - - - a #GstRTPBasePayload - - - - a #GstBuffer - - - - - - Push @list to the peer element of the payloader. The SSRC, payload type, -seqnum and timestamp of the RTP buffer will be updated first. - -This function takes ownership of @list. - - - a #GstFlowReturn. - - - - - a #GstRTPBasePayload - - - - a #GstBufferList - - - - - - Set the rtp options of the payloader. These options will be set in the caps -of the payloader. Subclasses must call this method before calling -gst_rtp_base_payload_push() or gst_rtp_base_payload_set_outcaps(). - - - - - - - a #GstRTPBasePayload - - - - the media type (typically "audio" or "video") - - - - if the payload type is dynamic - - - - the encoding name - - - - the clock rate of the media - - - - - - Configure the output caps with the optional parameters. - -Variable arguments should be in the form field name, field type -(as a GType), value(s). The last variable argument should be NULL. - - - %TRUE if the caps could be set. - - - - - a #GstRTPBasePayload - - - - the first field name or %NULL - - - - field values - - - - - - Enable or disable adding contributing sources to RTP packets from -#GstRTPSourceMeta. - - - - - - - a #GstRTPBasePayload - - - - whether to add contributing sources to RTP packets - - - - - - - - - Minimum duration of the packet data in ns (can't go above MTU) - - - - - - - Make the payloader timestamp packets according to the Rate-Control=no -behaviour specified in the ONVIF replay spec. - - - - Try to use the offset fields to generate perfect RTP timestamps. When this -option is disabled, RTP timestamps are generated from GST_BUFFER_PTS of -each payloaded buffer. The PTSes of buffers may not necessarily increment -with the amount of data in each input buffer, consider e.g. the case where -the buffer arrives from a network which means that the PTS is unrelated to -the amount of data. Because the RTP timestamps are generated from -GST_BUFFER_PTS this can result in RTP timestamps that also don't increment -with the amount of data in the payloaded packet. To circumvent this it is -possible to set the perfect rtptime option enabled. When this option is -enabled the payloader will increment the RTP timestamps based on -GST_BUFFER_OFFSET which relates to the amount of data in each packet -rather than the GST_BUFFER_PTS of each buffer and therefore the RTP -timestamps will more closely correlate with the amount of data in each -buffer. Currently GstRTPBasePayload is limited to handling perfect RTP -timestamps for audio streams. - - - - - - - Force buffers to be multiples of this duration in ns (0 disables) - - - - Make the RTP packets' timestamps be scaled with the segment's rate -(corresponding to RTSP speed parameter). Disabling this property means -the timestamps will not be affected by the set delivery speed (RTSP speed). - -Example: A server wants to allow streaming a recorded video in double -speed but still have the timestamps correspond to the position in the -video. This is achieved by the client setting RTSP Speed to 2 while the -server has this property disabled. - - - - - - - - - - Enable writing the CSRC field in allocated RTP header based on RTP source -information found in the input buffer's #GstRTPSourceMeta. - - - - - - - Various payloader statistics retrieved atomically (and are therefore -synchroized with each other), these can be used e.g. to generate an -RTP-Info header. This property return a GstStructure named -application/x-rtp-payload-stats containing the following fields relating to -the last processed buffer and current state of the stream being payloaded: - - * `clock-rate` :#G_TYPE_UINT, clock-rate of the stream - * `running-time` :#G_TYPE_UINT64, running time - * `seqnum` :#G_TYPE_UINT, sequence number, same as #GstRTPBasePayload:seqnum - * `timestamp` :#G_TYPE_UINT, RTP timestamp, same as #GstRTPBasePayload:timestamp - * `ssrc` :#G_TYPE_UINT, The SSRC in use - * `pt` :#G_TYPE_UINT, The Payload type in use, same as #GstRTPBasePayload:pt - * `seqnum-offset` :#G_TYPE_UINT, The current offset added to the seqnum - * `timestamp-offset` :#G_TYPE_UINT, The current offset added to the timestamp - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Base class for audio RTP payloader. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The GstRTPBuffer helper functions makes it easy to parse and create regular -#GstBuffer objects that contain RTP payloads. These buffers are typically of -'application/x-rtp' #GstCaps. - - - pointer to RTP buffer - - - - internal state - - - - array of data - - - - - - array of size - - - - - - array of #GstMapInfo - - - - - - Adds a RFC 5285 header extension with a one byte header to the end of the -RTP header. If there is already a RFC 5285 header extension with a one byte -header, the new extension will be appended. -It will not work if there is already a header extension that does not follow -the mechanism described in RFC 5285 or if there is a header extension with -a two bytes header as described in RFC 5285. In that case, use -gst_rtp_buffer_add_extension_twobytes_header() - - - %TRUE if header extension could be added - - - - - the RTP packet - - - - The ID of the header extension (between 1 and 14). - - - - location for data - - - - - - the size of the data in bytes - - - - - - Adds a RFC 5285 header extension with a two bytes header to the end of the -RTP header. If there is already a RFC 5285 header extension with a two bytes -header, the new extension will be appended. -It will not work if there is already a header extension that does not follow -the mechanism described in RFC 5285 or if there is a header extension with -a one byte header as described in RFC 5285. In that case, use -gst_rtp_buffer_add_extension_onebyte_header() - - - %TRUE if header extension could be added - - - - - the RTP packet - - - - Application specific bits - - - - The ID of the header extension - - - - location for data - - - - - - the size of the data in bytes - - - - - - Get the CSRC at index @idx in @buffer. - - - the CSRC at index @idx in host order. - - - - - the RTP packet - - - - the index of the CSRC to get - - - - - - Get the CSRC count of the RTP packet in @buffer. - - - the CSRC count of @buffer. - - - - - the RTP packet - - - - - - Check if the extension bit is set on the RTP packet in @buffer. - - - TRUE if @buffer has the extension bit set. - - - - - the RTP packet - - - - - - Similar to gst_rtp_buffer_get_extension_data, but more suitable for language -bindings usage. @bits will contain the extension 16 bits of custom data and -the extension data (not including the extension header) is placed in a new -#GBytes structure. - -If @rtp did not contain an extension, this function will return %NULL, with -@bits unchanged. If there is an extension header but no extension data then -an empty #GBytes will be returned. - - - A new #GBytes if an extension header was present -and %NULL otherwise. - - - - - the RTP packet - - - - location for header bits - - - - - - Get the extension data. @bits will contain the extension 16 bits of custom -data. @data will point to the data in the extension and @wordlen will contain -the length of @data in 32 bits words. - -If @buffer did not contain an extension, this function will return %FALSE -with @bits, @data and @wordlen unchanged. - - - TRUE if @buffer had the extension bit set. - - - - - the RTP packet - - - - location for result bits - - - - location for data - - - - - - location for length of @data in 32 bits words - - - - - - Parses RFC 5285 style header extensions with a one byte header. It will -return the nth extension with the requested id. - - - TRUE if @buffer had the requested header extension - - - - - the RTP packet - - - - The ID of the header extension to be read (between 1 and 14). - - - - Read the nth extension packet with the requested ID - - - - - location for data - - - - - - the size of the data in bytes - - - - - - Parses RFC 5285 style header extensions with a two bytes header. It will -return the nth extension with the requested id. - - - TRUE if @buffer had the requested header extension - - - - - the RTP packet - - - - Application specific bits - - - - The ID of the header extension to be read (between 1 and 14). - - - - Read the nth extension packet with the requested ID - - - - - location for data - - - - - - the size of the data in bytes - - - - - - Return the total length of the header in @buffer. This include the length of -the fixed header, the CSRC list and the extension header. - - - The total length of the header in @buffer. - - - - - the RTP packet - - - - - - Check if the marker bit is set on the RTP packet in @buffer. - - - TRUE if @buffer has the marker bit set. - - - - - the RTP packet - - - - - - Return the total length of the packet in @buffer. - - - The total length of the packet in @buffer. - - - - - the RTP packet - - - - - - Check if the padding bit is set on the RTP packet in @buffer. - - - TRUE if @buffer has the padding bit set. - - - - - the RTP packet - - - - - - Get a pointer to the payload data in @buffer. This pointer is valid as long -as a reference to @buffer is held. - - - A pointer -to the payload data in @buffer. - - - - - - - the RTP packet - - - - - - Create a buffer of the payload of the RTP packet in @buffer. This function -will internally create a subbuffer of @buffer so that a memcpy can be -avoided. - - - A new buffer with the data of the payload. - - - - - the RTP packet - - - - - - Similar to gst_rtp_buffer_get_payload, but more suitable for language -bindings usage. The return value is a pointer to a #GBytes structure -containing the payload data in @rtp. - - - A new #GBytes containing the payload data in @rtp. - - - - - the RTP packet - - - - - - Get the length of the payload of the RTP packet in @buffer. - - - The length of the payload in @buffer. - - - - - the RTP packet - - - - - - Create a subbuffer of the payload of the RTP packet in @buffer. @offset bytes -are skipped in the payload and the subbuffer will be of size @len. -If @len is -1 the total payload starting from @offset is subbuffered. - - - A new buffer with the specified data of the payload. - - - - - the RTP packet - - - - the offset in the payload - - - - the length in the payload - - - - - - Get the payload type of the RTP packet in @buffer. - - - The payload type. - - - - - the RTP packet - - - - - - Get the sequence number of the RTP packet in @buffer. - - - The sequence number in host order. - - - - - the RTP packet - - - - - - Get the SSRC of the RTP packet in @buffer. - - - the SSRC of @buffer in host order. - - - - - the RTP packet - - - - - - Get the timestamp of the RTP packet in @buffer. - - - The timestamp in host order. - - - - - the RTP packet - - - - - - Get the version number of the RTP packet in @buffer. - - - The version of @buffer. - - - - - the RTP packet - - - - - - Set the amount of padding in the RTP packet in @buffer to -@len. If @len is 0, the padding is removed. - -NOTE: This function does not work correctly. - - - - - - - the RTP packet - - - - the new amount of padding - - - - - - Modify the CSRC at index @idx in @buffer to @csrc. - - - - - - - the RTP packet - - - - the CSRC index to set - - - - the CSRC in host order to set at @idx - - - - - - Set the extension bit on the RTP packet in @buffer to @extension. - - - - - - - the RTP packet - - - - the new extension - - - - - - Set the extension bit of the rtp buffer and fill in the @bits and @length of the -extension header. If the existing extension data is not large enough, it will -be made larger. - - - True if done. - - - - - the RTP packet - - - - the bits specific for the extension - - - - the length that counts the number of 32-bit words in -the extension, excluding the extension header ( therefore zero is a valid length) - - - - - - Set the marker bit on the RTP packet in @buffer to @marker. - - - - - - - the RTP packet - - - - the new marker - - - - - - Set the total @rtp size to @len. The data in the buffer will be made -larger if needed. Any padding will be removed from the packet. - - - - - - - the RTP packet - - - - the new packet length - - - - - - Set the padding bit on the RTP packet in @buffer to @padding. - - - - - - - the buffer - - - - the new padding - - - - - - Set the payload type of the RTP packet in @buffer to @payload_type. - - - - - - - the RTP packet - - - - the new type - - - - - - Set the sequence number of the RTP packet in @buffer to @seq. - - - - - - - the RTP packet - - - - the new sequence number - - - - - - Set the SSRC on the RTP packet in @buffer to @ssrc. - - - - - - - the RTP packet - - - - the new SSRC - - - - - - Set the timestamp of the RTP packet in @buffer to @timestamp. - - - - - - - the RTP packet - - - - the new timestamp - - - - - - Set the version of the RTP packet in @buffer to @version. - - - - - - - the RTP packet - - - - the new version - - - - - - Unmap @rtp previously mapped with gst_rtp_buffer_map(). - - - - - - - a #GstRTPBuffer - - - - - - Allocate enough data in @buffer to hold an RTP packet with @csrc_count CSRCs, -a payload length of @payload_len and padding of @pad_len. -@buffer must be writable and all previous memory in @buffer will be freed. -If @pad_len is >0, the padding bit will be set. All other RTP header fields -will be set to 0/FALSE. - - - - - - - a #GstBuffer - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Calculate the header length of an RTP packet with @csrc_count CSRC entries. -An RTP packet can have at most 15 CSRC entries. - - - The length of an RTP header with @csrc_count CSRC entries. - - - - - the number of CSRC entries - - - - - - Calculate the total length of an RTP packet with a payload size of @payload_len, -a padding of @pad_len and a @csrc_count CSRC entries. - - - The total length of an RTP header with given parameters. - - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Calculate the length of the payload of an RTP packet with size @packet_len, -a padding of @pad_len and a @csrc_count CSRC entries. - - - The length of the payload of an RTP packet with given parameters. - - - - - the length of the total RTP packet - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Compare two sequence numbers, taking care of wraparounds. This function -returns the difference between @seqnum1 and @seqnum2. - - - a negative value if @seqnum1 is bigger than @seqnum2, 0 if they -are equal or a positive value if @seqnum1 is smaller than @segnum2. - - - - - a sequence number - - - - a sequence number - - - - - - Get the default clock-rate for the static payload type @payload_type. - - - the default clock rate or -1 if the payload type is not static or -the clock-rate is undefined. - - - - - the static payload type - - - - - - Update the @exttimestamp field with the extended timestamp of @timestamp -For the first call of the method, @exttimestamp should point to a location -with a value of -1. - -This function is able to handle both forward and backward timestamps taking -into account: - - timestamp wraparound making sure that the returned value is properly increased. - - timestamp unwraparound making sure that the returned value is properly decreased. - - - The extended timestamp of @timestamp or 0 if the result can't go anywhere backwards. - - - - - a previous extended timestamp - - - - a new timestamp - - - - - - Similar to gst_rtp_buffer_get_extension_onebyte_header, but working -on the #GBytes you get from gst_rtp_buffer_get_extension_bytes. -Parses RFC 5285 style header extensions with a one byte header. It will -return the nth extension with the requested id. - - - TRUE if @bytes had the requested header extension - - - - - #GBytes - - - - The bit-pattern. Anything but 0xBEDE is rejected. - - - - The ID of the header extension to be read (between 1 and 14). - - - - Read the nth extension packet with the requested ID - - - - - location for data - - - - - - the size of the data in bytes - - - - - - Map the contents of @buffer into @rtp. - - - %TRUE if @buffer could be mapped. - - - - - a #GstBuffer - - - - #GstMapFlags - - - - a #GstRTPBuffer - - - - - - Allocate a new #GstBuffer with enough data to hold an RTP packet with -@csrc_count CSRCs, a payload length of @payload_len and padding of @pad_len. -All other RTP header fields will be set to 0/FALSE. - - - A newly allocated buffer that can hold an RTP packet with given -parameters. - - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Create a new #GstBuffer that can hold an RTP packet that is exactly -@packet_len long. The length of the payload depends on @pad_len and -@csrc_count and can be calculated with gst_rtp_buffer_calc_payload_len(). -All RTP header fields will be set to 0/FALSE. - - - A newly allocated buffer that can hold an RTP packet of @packet_len. - - - - - the total length of the packet - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Create a new buffer and set the data to a copy of @len -bytes of @data and the size to @len. The data will be freed when the buffer -is freed. - - - A newly allocated buffer with a copy of @data and of size @len. - - - - - data for the new - buffer - - - - - - the length of data - - - - - - Create a new buffer and set the data and size of the buffer to @data and @len -respectively. @data will be freed when the buffer is unreffed, so this -function transfers ownership of @data to the new buffer. - - - A newly allocated buffer with @data and of size @len. - - - - - - data for the new buffer - - - - - - the length of data - - - - - - - Additional RTP buffer flags. These flags can potentially be used on any -buffers carrying RTP packets. - -Note that these are only valid for #GstCaps of type: application/x-rtp (x-rtcp). -They can conflict with other extended buffer flags. - - The #GstBuffer was once wrapped - in a retransmitted packet as specified by RFC 4588. - - - The packet represents redundant RTP packet. - The flag is used in gstrtpstorage to be able to hold the packetback - and use it only for recovery from packet loss. - Since: 1.14 - - - Offset to define more flags. - - - - Additional mapping flags for gst_rtp_buffer_map(). - - Skip mapping and validation of RTP - padding and RTP pad count when present. Useful for buffers where - the padding may be encrypted. - - - Offset to define more flags - - - - Standard predefined fixed payload types. - -The official list is at: -http://www.iana.org/assignments/rtp-parameters - -Audio: -reserved: 19 -unassigned: 20-23, - -Video: -unassigned: 24, 27, 29, 30, 35-71, 77-95 -Reserved for RTCP conflict avoidance: 72-76 - - ITU-T G.711. mu-law audio (RFC 3551) - - - RFC 3551 says reserved - - - RFC 3551 says reserved - - - GSM audio - - - ITU G.723.1 audio - - - IMA ADPCM wave type (RFC 3551) - - - IMA ADPCM wave type (RFC 3551) - - - experimental linear predictive encoding - - - ITU-T G.711 A-law audio (RFC 3551) - - - ITU-T G.722 (RFC 3551) - - - stereo PCM - - - mono PCM - - - EIA & TIA standard IS-733 - - - Comfort Noise (RFC 3389) - - - Audio MPEG 1-3. - - - ITU-T G.728 Speech coder (RFC 3551) - - - IMA ADPCM wave type (RFC 3551) - - - IMA ADPCM wave type (RFC 3551) - - - ITU-T G.729 Speech coder (RFC 3551) - - - See RFC 2029 - - - ISO Standards 10918-1 and 10918-2 (RFC 2435) - - - nv encoding by Ron Frederick - - - ITU-T Recommendation H.261 (RFC 2032) - - - Video MPEG 1 & 2 (RFC 2250) - - - MPEG-2 transport stream (RFC 2250) - - - Video H263 (RFC 2190) - - - - Structure holding default payload type information. - - - payload type, -1 means dynamic - - - - the media type(s), usually "audio", "video", "application", "text", -"message". - - - - the encoding name of @pt - - - - default clock rate, 0 = unknown/variable - - - - encoding parameters. For audio this is the number of -channels. NULL = not applicable. - - - - the bitrate of the media. 0 = unknown/variable. - - - - - - - - - Get the #GstRTPPayloadInfo for @media and @encoding_name. This function is -mostly used to get the default clock-rate and bandwidth for dynamic payload -types specified with @media and @encoding name. - -The search for @encoding_name will be performed in a case insensitive way. - - - a #GstRTPPayloadInfo or NULL when no info could be found. - - - - - the media to find - - - - the encoding name to find - - - - - - Get the #GstRTPPayloadInfo for @payload_type. This function is -mostly used to get the default clock-rate and bandwidth for static payload -types specified with @payload_type. - - - a #GstRTPPayloadInfo or NULL when no info could be found. - - - - - the payload_type to find - - - - - - - The transfer profile to use. - - invalid profile - - - the Audio/Visual profile (RFC 3551) - - - the secure Audio/Visual profile (RFC 3711) - - - the Audio/Visual profile with feedback (RFC 4585) - - - the secure Audio/Visual profile with feedback (RFC 5124) - - - - Meta describing the source(s) of the buffer. - - - parent #GstMeta - - - - the SSRC - - - - whether @ssrc is set and valid - - - - pointer to the CSRCs - - - - - - number of elements in @csrc - - - - Appends @csrc to the list of contributing sources in @meta. - - - %TRUE if all elements in @csrc was added, %FALSE otherwise. - - - - - a #GstRTPSourceMeta - - - - the csrcs to append - - - - number of elements in @csrc - - - - - - Count the total number of RTP sources found in @meta, both SSRC and CSRC. - - - The number of RTP sources - - - - - a #GstRTPSourceMeta - - - - - - Sets @ssrc in @meta. If @ssrc is %NULL the ssrc of @meta will be unset. - - - %TRUE on success, %FALSE otherwise. - - - - - a #GstRTPSourceMeta - - - - pointer to the SSRC - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get access to the configured MTU of @payload. - - - - a #GstRTPBasePayload - - - - - Get access to the configured payload type of @payload. - - - - a #GstRTPBasePayload - - - - - Get access to the sinkpad of @payload. - - - - a #GstRTPBasePayload - - - - - Get access to the srcpad of @payload. - - - - a #GstRTPBasePayload - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Check if @pt is a dynamic payload type. - - - - a payload type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The supported RTP version 2. - - - - - Attaches RTP source information to @buffer. - - - the #GstRTPSourceMeta on @buffer. - - - - - a #GstBuffer - - - - pointer to the SSRC - - - - pointer to the CSRCs - - - - number of elements in @csrc - - - - - - Find the #GstRTPSourceMeta on @buffer. - - - the #GstRTPSourceMeta or %NULL when there -is no such metadata on @buffer. - - - - - a #GstBuffer - - - - - - Open @buffer for reading or writing, depending on @flags. The resulting RTCP -buffer state is stored in @rtcp. - - - - - - - a buffer with an RTCP packet - - - - flags for the mapping - - - - resulting #GstRTCPBuffer - - - - - - Create a new buffer for constructing RTCP packets. The packet will have a -maximum size of @mtu. - - - A newly allocated buffer. - - - - - the maximum mtu size. - - - - - - Create a new buffer and set the data to a copy of @len -bytes of @data and the size to @len. The data will be freed when the buffer -is freed. - - - A newly allocated buffer with a copy of @data and of size @len. - - - - - data for the new buffer - - - - - - the length of data - - - - - - Create a new buffer and set the data and size of the buffer to @data and @len -respectively. @data will be freed when the buffer is unreffed, so this -function transfers ownership of @data to the new buffer. - - - A newly allocated buffer with @data and of size @len. - - - - - data for the new buffer - - - - - - the length of data - - - - - - Check if the data pointed to by @buffer is a valid RTCP packet using -gst_rtcp_buffer_validate_data(). - - - TRUE if @buffer is a valid RTCP packet. - - - - - the buffer to validate - - - - - - Check if the @data and @size point to the data of a valid compound, -non-reduced size RTCP packet. -Use this function to validate a packet before using the other functions in -this module. - - - TRUE if the data points to a valid RTCP packet. - - - - - the data to validate - - - - - - the length of @data to validate - - - - - - Check if the @data and @size point to the data of a valid RTCP packet. -Use this function to validate a packet before using the other functions in -this module. - -This function is updated to support reduced size rtcp packets according to -RFC 5506 and will validate full compound RTCP packets as well as reduced -size RTCP packets. - - - TRUE if the data points to a valid RTCP packet. - - - - - the data to validate - - - - - - the length of @data to validate - - - - - - Check if the data pointed to by @buffer is a valid RTCP packet using -gst_rtcp_buffer_validate_reduced(). - - - TRUE if @buffer is a valid RTCP packet. - - - - - the buffer to validate - - - - - - Converts an NTP time to UNIX nanoseconds. @ntptime can typically be -the NTP time of an SR RTCP message and contains, in the upper 32 bits, the -number of seconds since 1900 and, in the lower 32 bits, the fractional -seconds. The resulting value will be the number of nanoseconds since 1970. - - - the UNIX time for @ntptime in nanoseconds. - - - - - an NTP timestamp - - - - - - Convert @name into a @GstRTCPSDESType. @name is typically a key in a -#GstStructure containing SDES items. - - - the #GstRTCPSDESType for @name or #GST_RTCP_SDES_PRIV when @name -is a private sdes item. - - - - - a SDES name - - - - - - Converts @type to the string equivalent. The string is typically used as a -key in a #GstStructure containing SDES items. - - - the string equivalent of @type - - - - - a #GstRTCPSDESType - - - - - - Converts a UNIX timestamp in nanoseconds to an NTP time. The caller should -pass a value with nanoseconds since 1970. The NTP time will, in the upper -32 bits, contain the number of seconds since 1900 and, in the lower 32 -bits, the fractional seconds. The resulting value can be used as an ntptime -for constructing SR RTCP packets. - - - the NTP time for @unixtime. - - - - - an UNIX timestamp in nanoseconds - - - - - - Allocate enough data in @buffer to hold an RTP packet with @csrc_count CSRCs, -a payload length of @payload_len and padding of @pad_len. -@buffer must be writable and all previous memory in @buffer will be freed. -If @pad_len is >0, the padding bit will be set. All other RTP header fields -will be set to 0/FALSE. - - - - - - - a #GstBuffer - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Calculate the header length of an RTP packet with @csrc_count CSRC entries. -An RTP packet can have at most 15 CSRC entries. - - - The length of an RTP header with @csrc_count CSRC entries. - - - - - the number of CSRC entries - - - - - - Calculate the total length of an RTP packet with a payload size of @payload_len, -a padding of @pad_len and a @csrc_count CSRC entries. - - - The total length of an RTP header with given parameters. - - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Calculate the length of the payload of an RTP packet with size @packet_len, -a padding of @pad_len and a @csrc_count CSRC entries. - - - The length of the payload of an RTP packet with given parameters. - - - - - the length of the total RTP packet - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Compare two sequence numbers, taking care of wraparounds. This function -returns the difference between @seqnum1 and @seqnum2. - - - a negative value if @seqnum1 is bigger than @seqnum2, 0 if they -are equal or a positive value if @seqnum1 is smaller than @segnum2. - - - - - a sequence number - - - - a sequence number - - - - - - Get the default clock-rate for the static payload type @payload_type. - - - the default clock rate or -1 if the payload type is not static or -the clock-rate is undefined. - - - - - the static payload type - - - - - - Update the @exttimestamp field with the extended timestamp of @timestamp -For the first call of the method, @exttimestamp should point to a location -with a value of -1. - -This function is able to handle both forward and backward timestamps taking -into account: - - timestamp wraparound making sure that the returned value is properly increased. - - timestamp unwraparound making sure that the returned value is properly decreased. - - - The extended timestamp of @timestamp or 0 if the result can't go anywhere backwards. - - - - - a previous extended timestamp - - - - a new timestamp - - - - - - Similar to gst_rtp_buffer_get_extension_onebyte_header, but working -on the #GBytes you get from gst_rtp_buffer_get_extension_bytes. -Parses RFC 5285 style header extensions with a one byte header. It will -return the nth extension with the requested id. - - - TRUE if @bytes had the requested header extension - - - - - #GBytes - - - - The bit-pattern. Anything but 0xBEDE is rejected. - - - - The ID of the header extension to be read (between 1 and 14). - - - - Read the nth extension packet with the requested ID - - - - - location for data - - - - - - the size of the data in bytes - - - - - - Map the contents of @buffer into @rtp. - - - %TRUE if @buffer could be mapped. - - - - - a #GstBuffer - - - - #GstMapFlags - - - - a #GstRTPBuffer - - - - - - Allocate a new #GstBuffer with enough data to hold an RTP packet with -@csrc_count CSRCs, a payload length of @payload_len and padding of @pad_len. -All other RTP header fields will be set to 0/FALSE. - - - A newly allocated buffer that can hold an RTP packet with given -parameters. - - - - - the length of the payload - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Create a new #GstBuffer that can hold an RTP packet that is exactly -@packet_len long. The length of the payload depends on @pad_len and -@csrc_count and can be calculated with gst_rtp_buffer_calc_payload_len(). -All RTP header fields will be set to 0/FALSE. - - - A newly allocated buffer that can hold an RTP packet of @packet_len. - - - - - the total length of the packet - - - - the amount of padding - - - - the number of CSRC entries - - - - - - Create a new buffer and set the data to a copy of @len -bytes of @data and the size to @len. The data will be freed when the buffer -is freed. - - - A newly allocated buffer with a copy of @data and of size @len. - - - - - data for the new - buffer - - - - - - the length of data - - - - - - Create a new buffer and set the data and size of the buffer to @data and @len -respectively. @data will be freed when the buffer is unreffed, so this -function transfers ownership of @data to the new buffer. - - - A newly allocated buffer with @data and of size @len. - - - - - - data for the new buffer - - - - - - the length of data - - - - - - Reads the NTP time from the @size NTP-56 extension bytes in @data and store the -result in @ntptime. - - - %TRUE on success. - - - - - the data to read from - - - - - - the size of @data - - - - the result NTP time - - - - - - Reads the NTP time from the @size NTP-64 extension bytes in @data and store the -result in @ntptime. - - - %TRUE on success. - - - - - the data to read from - - - - - - the size of @data - - - - the result NTP time - - - - - - Writes the NTP time in @ntptime to the format required for the NTP-56 header -extension. @data must hold at least #GST_RTP_HDREXT_NTP_56_SIZE bytes. - - - %TRUE on success. - - - - - the data to write to - - - - the size of @data - - - - the NTP time - - - - - - Writes the NTP time in @ntptime to the format required for the NTP-64 header -extension. @data must hold at least #GST_RTP_HDREXT_NTP_64_SIZE bytes. - - - %TRUE on success. - - - - - the data to write to - - - - the size of @data - - - - the NTP time - - - - - - Get the #GstRTPPayloadInfo for @media and @encoding_name. This function is -mostly used to get the default clock-rate and bandwidth for dynamic payload -types specified with @media and @encoding name. - -The search for @encoding_name will be performed in a case insensitive way. - - - a #GstRTPPayloadInfo or NULL when no info could be found. - - - - - the media to find - - - - the encoding name to find - - - - - - Get the #GstRTPPayloadInfo for @payload_type. This function is -mostly used to get the default clock-rate and bandwidth for static payload -types specified with @payload_type. - - - a #GstRTPPayloadInfo or NULL when no info could be found. - - - - - the payload_type to find - - - - - - - - - - - - - - - - - - diff --git a/gir-files/GstRtsp-1.0.gir b/gir-files/GstRtsp-1.0.gir deleted file mode 100644 index de1fa1901..000000000 --- a/gir-files/GstRtsp-1.0.gir +++ /dev/null @@ -1,4769 +0,0 @@ - - - - - - - - - - - - - - - - - - - RTSP Authentication credentials - - - a #GstRTSPAuthMethod - - - - A NULL-terminated array of #GstRTSPAuthParam - - - - The authorization for the basic schem - - - - - Authentication methods, ordered by strength - - no authentication - - - basic authentication - - - digest authentication - - - - RTSP Authentication parameter - - - The name of the parameter - - - - The value of the parameter - - - - - - - - - - - - - - - - - - - - - - - - - - - This object manages the RTSP connection to the server. It provides function -to receive and send bytes and messages. - - - Clear the list of authentication directives stored in @conn. - - - - - - - a #GstRTSPConnection - - - - - - Close the connected @conn. After this call, the connection is in the same -state as when it was first created. - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - - - Attempt to connect to the url of @conn made with -gst_rtsp_connection_create(). If @timeout is %NULL this function can block -forever. If @timeout contains a valid timeout, this function will return -#GST_RTSP_ETIMEOUT after the timeout expired. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK when a connection could be made. - - - - - a #GstRTSPConnection - - - - a GTimeVal timeout - - - - - - Attempt to connect to the url of @conn made with -gst_rtsp_connection_create(). If @timeout is 0 this function can block -forever. If @timeout contains a valid timeout, this function will return -#GST_RTSP_ETIMEOUT after the timeout expired. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK when a connection could be made. - - - - - a #GstRTSPConnection - - - - a timeout in microseconds - - - - - - Attempt to connect to the url of @conn made with -gst_rtsp_connection_create(). If @timeout is %NULL this function can block -forever. If @timeout contains a valid timeout, this function will return -#GST_RTSP_ETIMEOUT after the timeout expired. If @conn is set to tunneled, -@response will contain a response to the tunneling request messages. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK when a connection could be made. - - - - - a #GstRTSPConnection - - - - a GTimeVal timeout - - - - a #GstRTSPMessage - - - - - - Attempt to connect to the url of @conn made with -gst_rtsp_connection_create(). If @timeout is 0 this function can block -forever. If @timeout contains a valid timeout, this function will return -#GST_RTSP_ETIMEOUT after the timeout expired. If @conn is set to tunneled, -@response will contain a response to the tunneling request messages. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK when a connection could be made. - - - - - a #GstRTSPConnection - - - - a timeout in microseconds - - - - a #GstRTSPMessage - - - - - - If @conn received the first tunnel connection and @conn2 received -the second tunnel connection, link the two connections together so that -@conn manages the tunneled connection. - -After this call, @conn2 cannot be used anymore and must be freed with -gst_rtsp_connection_free(). - -If @conn2 is %NULL then only the base64 decoding context will be setup for -@conn. - - - return GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - a #GstRTSPConnection or %NULL - - - - - - Start or stop the flushing action on @conn. When flushing, all current -and future actions on @conn will return #GST_RTSP_EINTR until the connection -is set to non-flushing mode again. - - - #GST_RTSP_OK. - - - - - a #GstRTSPConnection - - - - start or stop the flush - - - - - - Close and free @conn. - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - - - Retrieve the IP address of the other end of @conn. - - - The IP address as a string. this value remains valid until the -connection is closed. - - - - - a #GstRTSPConnection - - - - - - Get the file descriptor for reading. - - - the file descriptor used for reading or %NULL on -error. The file descriptor remains valid until the connection is closed. - - - - - a #GstRTSPConnection - - - - - - - - %TRUE if the #GstRTSPConnection remembers the session id in the -last response to set it on any further request. - - - - - a #GstRTSPConnection - - - - - - Get the TLS connection of @conn. - -For client side this will return the #GTlsClientConnection when connected -over TLS. - -For server side connections, this function will create a GTlsServerConnection -when called the first time and will return that same connection on subsequent -calls. The server is then responsible for configuring the TLS connection. - - - the TLS connection for @conn. - - - - - a #GstRTSPConnection - - - - - - Gets the anchor certificate authorities database that will be used -after a server certificate can't be verified with the default -certificate database. - - - the anchor certificate authorities database, or NULL if no -database has been previously set. Use g_object_unref() to release the -certificate database. - - - - - a #GstRTSPConnection - - - - - - Gets a #GTlsInteraction object to be used when the connection or certificate -database need to interact with the user. This will be used to prompt the -user for passwords where necessary. - - - a reference on the #GTlsInteraction. Use -g_object_unref() to release. - - - - - a #GstRTSPConnection - - - - - - Gets the TLS validation flags used to verify the peer certificate -when a TLS connection is established. - - - the validationg flags. - - - - - a #GstRTSPConnection - - - - - - Get the tunnel session id the connection. - - - returns a non-empty string if @conn is being tunneled over HTTP. - - - - - a #GstRTSPConnection - - - - - - Retrieve the URL of the other end of @conn. - - - The URL. This value remains valid until the -connection is freed. - - - - - a #GstRTSPConnection - - - - - - Get the file descriptor for writing. - - - the file descriptor used for writing or NULL on -error. The file descriptor remains valid until the connection is closed. - - - - - a #GstRTSPConnection - - - - - - Get the tunneling state of the connection. - - - if @conn is using HTTP tunneling. - - - - - a #GstRTSPConnection - - - - - - Calculate the next timeout for @conn, storing the result in @timeout. - - - #GST_RTSP_OK. - - - - - a #GstRTSPConnection - - - - a timeout - - - - - - Calculate the next timeout for @conn - - - #the next timeout in microseconds - - - - - a #GstRTSPConnection - - - - - - Wait up to the specified @timeout for the connection to become available for -at least one of the operations specified in @events. When the function returns -with #GST_RTSP_OK, @revents will contain a bitmask of available operations on -@conn. - -@timeout can be %NULL, in which case this function might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - a bitmask of #GstRTSPEvent flags to check - - - - location for result flags - - - - a timeout - - - - - - Wait up to the specified @timeout for the connection to become available for -at least one of the operations specified in @events. When the function returns -with #GST_RTSP_OK, @revents will contain a bitmask of available operations on -@conn. - -@timeout can be 0, in which case this function might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - a bitmask of #GstRTSPEvent flags to check - - - - location for result flags - - - - a timeout in microseconds - - - - - - Attempt to read @size bytes into @data from the connected @conn, blocking up to -the specified @timeout. @timeout can be %NULL, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the data to read - - - - the size of @data - - - - a timeout value or %NULL - - - - - - Attempt to read @size bytes into @data from the connected @conn, blocking up to -the specified @timeout. @timeout can be 0, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the data to read - - - - the size of @data - - - - a timeout value in microseconds - - - - - - Attempt to read into @message from the connected @conn, blocking up to -the specified @timeout. @timeout can be %NULL, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the message to read - - - - a timeout value or %NULL - - - - - - Attempt to read into @message from the connected @conn, blocking up to -the specified @timeout. @timeout can be 0, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the message to read - - - - a timeout value or 0 - - - - - - Reset the timeout of @conn. - - - #GST_RTSP_OK. - - - - - a #GstRTSPConnection - - - - - - Attempt to send @message to the connected @conn, blocking up to -the specified @timeout. @timeout can be %NULL, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the message to send - - - - a timeout value or %NULL - - - - - - Attempt to send @messages to the connected @conn, blocking up to -the specified @timeout. @timeout can be %NULL, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the messages to send - - - - - - the number of messages to send - - - - a timeout value or %NULL - - - - - - Attempt to send @messages to the connected @conn, blocking up to -the specified @timeout. @timeout can be 0, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on Since. - - - - - a #GstRTSPConnection - - - - the messages to send - - - - - - the number of messages to send - - - - a timeout value in microseconds - - - - - - Attempt to send @message to the connected @conn, blocking up to -the specified @timeout. @timeout can be 0, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the message to send - - - - a timeout value in microseconds - - - - - - Sets a custom accept-certificate function for checking certificates for -validity. This will directly map to #GTlsConnection 's "accept-certificate" -signal and be performed after the default checks of #GstRTSPConnection -(checking against the #GTlsDatabase with the given #GTlsCertificateFlags) -have failed. If no #GTlsDatabase is set on this connection, only @func will -be called. - - - - - - - a #GstRTSPConnection - - - - a #GstRTSPConnectionAcceptCertificateFunc to check certificates - - - - User data passed to @func - - - - #GDestroyNotify for @user_data - - - - - - Configure @conn for authentication mode @method with @user and @pass as the -user and password respectively. - - - #GST_RTSP_OK. - - - - - a #GstRTSPConnection - - - - authentication method - - - - the user - - - - the password - - - - - - Setup @conn with authentication directives. This is not necessary for -methods #GST_RTSP_AUTH_NONE and #GST_RTSP_AUTH_BASIC. For -#GST_RTSP_AUTH_DIGEST, directives should be taken from the digest challenge -in the WWW-Authenticate response header and can include realm, domain, -nonce, opaque, stale, algorithm, qop as per RFC2617. - - - - - - - a #GstRTSPConnection - - - - authentication directive - - - - value - - - - - - Configure @conn to use the specified Content-Length limit. -Both requests and responses are validated. If content-length is -exceeded, ENOMEM error will be returned. - - - - - - - a #GstRTSPConnection - - - - Content-Length limit - - - - - - By setting the HTTP mode to %TRUE the message parsing will support HTTP -messages in addition to the RTSP messages. It will also disable the -automatic handling of setting up an HTTP tunnel. - - - - - - - a #GstRTSPConnection - - - - %TRUE to enable manual HTTP mode - - - - - - Set the IP address of the server. - - - - - - - a #GstRTSPConnection - - - - an ip address - - - - - - Set the proxy host and port. - - - #GST_RTSP_OK. - - - - - a #GstRTSPConnection - - - - the proxy host - - - - the proxy port - - - - - - Configure @conn to use the specified DSCP value. - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - DSCP value - - - - - - Sets if the #GstRTSPConnection should remember the session id from the last -response received and force it onto any further requests. - -The default value is %TRUE - - - - - - - a #GstRTSPConnection - - - - %TRUE if the connection should remember the session id - - - - - - Sets the anchor certificate authorities database. This certificate -database will be used to verify the server's certificate in case it -can't be verified with the default certificate database first. - - - - - - - a #GstRTSPConnection - - - - a #GTlsDatabase - - - - - - Sets a #GTlsInteraction object to be used when the connection or certificate -database need to interact with the user. This will be used to prompt the -user for passwords where necessary. - - - - - - - a #GstRTSPConnection - - - - a #GTlsInteraction - - - - - - Sets the TLS validation flags to be used to verify the peer -certificate when a TLS connection is established. - - - TRUE if the validation flags are set correctly, or FALSE if -@conn is NULL or is not a TLS connection. - - - - - a #GstRTSPConnection - - - - the validation flags. - - - - - - Set the HTTP tunneling state of the connection. This must be configured before -the @conn is connected. - - - - - - - a #GstRTSPConnection - - - - the new state - - - - - - Attempt to write @size bytes of @data to the connected @conn, blocking up to -the specified @timeout. @timeout can be %NULL, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the data to write - - - - the size of @data - - - - a timeout value or %NULL - - - - - - Attempt to write @size bytes of @data to the connected @conn, blocking up to -the specified @timeout. @timeout can be 0, in which case this function -might block forever. - -This function can be cancelled with gst_rtsp_connection_flush(). - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPConnection - - - - the data to write - - - - the size of @data - - - - a timeout value or 0 - - - - - - Accept a new connection on @socket and create a new #GstRTSPConnection for -handling communication on new socket. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a socket - - - - storage for a #GstRTSPConnection - - - - a #GCancellable to cancel the operation - - - - - - Create a newly allocated #GstRTSPConnection from @url and store it in @conn. -The connection will not yet attempt to connect to @url, use -gst_rtsp_connection_connect(). - -A copy of @url will be made. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a #GstRTSPUrl - - - - storage for a #GstRTSPConnection - - - - - - Create a new #GstRTSPConnection for handling communication on the existing -socket @socket. The @initial_buffer contains zero terminated data already -read from @socket which should be used before starting to read new data. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a #GSocket - - - - the IP address of the other end - - - - the port used by the other end - - - - data already read from @fd - - - - storage for a #GstRTSPConnection - - - - - - - - - - - - - - - - - - - - - - - - - - - The possible events for the connection. - - connection is readable - - - connection is writable - - - - This interface is implemented e.g. by the Windows Media Streaming RTSP - exentension (rtspwms) and the RealMedia RTSP extension (rtspreal). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An interface representing RTSP extensions. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The possible network families. - - unknown network family - - - internet - - - internet V6 - - - - Enumeration of rtsp header fields - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The different transport methods. - - invalid transport flag - - - stream data over UDP - - - stream data over UDP multicast - - - stream data over TCP - - - stream data tunneled over HTTP. - - - encrypt TCP and HTTP with TLS - - - - Provides methods for creating and parsing request, response and data messages. - - - the message type - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Add a header with key @field and @value to @msg. This function takes a copy -of @value. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - the value of the header - - - - - - Add a header with key @header and @value to @msg. This function takes a copy -of @value. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - header string - - - - the value of the header - - - - - - Append the currently configured headers in @msg to the #GString @str suitable -for transmission. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - a string - - - - - - Allocate a new copy of @msg and store the result in @copy. The value in -@copy should be release with gst_rtsp_message_free function. - - - a #GstRTSPResult - - - - - a #GstRTSPMessage - - - - pointer to new #GstRTSPMessage - - - - - - Dump the contents of @msg to stdout. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - - - Free the memory used by @msg. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - - - Get the body of @msg. @data remains valid for as long as @msg is valid and -unchanged. - -If the message body was set as a #GstBuffer before this will cause the data -to be copied and stored in the message. The #GstBuffer will no longer be -kept in the message. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - location for the data - - - - - - location for the size of @data - - - - - - Get the body of @msg. @buffer remains valid for as long as @msg is valid and -unchanged. - -If body data was set from raw memory instead of a #GstBuffer this function -will always return %NULL. The caller can check if there is a body buffer by -calling gst_rtsp_message_has_body_buffer(). - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - location for the buffer - - - - - - Get the @indx header value with key @field from @msg. The result in @value -stays valid as long as it remains present in @msg. - - - #GST_RTSP_OK when @field was found, #GST_RTSP_ENOTIMPL if the key -was not found. - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - pointer to hold the result - - - - the index of the header - - - - - - Get the @index header value with key @header from @msg. The result in @value -stays valid as long as it remains present in @msg. - - - #GST_RTSP_OK when @field was found, #GST_RTSP_ENOTIMPL if the key -was not found. - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - pointer to hold the result - - - - the index of the header - - - - - - Get the message type of @msg. - - - the message type. - - - - - a #GstRTSPMessage - - - - - - Checks if @msg has a body and the body is stored as #GstBuffer. - - - %TRUE if @msg has a body and it's stored as #GstBuffer, %FALSE -otherwise. - - - - - a #GstRTSPMessage - - - - - - Initialize @msg. This function is mostly used when @msg is allocated on the -stack. The reverse operation of this is gst_rtsp_message_unset(). - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - - - Initialize a new data #GstRTSPMessage for @channel. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - a channel - - - - - - Initialize @msg as a request message with @method and @uri. To clear @msg -again, use gst_rtsp_message_unset(). - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - the request method to use - - - - the uri of the request - - - - - - Initialize @msg with @code and @reason. - -When @reason is %NULL, the default reason for @code will be used. - -When @request is not %NULL, the relevant headers will be copied to the new -response message. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - the status code - - - - the status reason or %NULL - - - - the request that triggered the response or %NULL - - - - - - Parses the credentials given in a WWW-Authenticate or Authorization header. - - - - %NULL-terminated array of GstRTSPAuthCredential or %NULL. - - - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - - - Parse the data message @msg and store the channel in @channel. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - location to hold the channel - - - - - - Parse the request message @msg and store the values @method, @uri and -@version. The result locations can be %NULL if one is not interested in its -value. - -@uri remains valid for as long as @msg is valid and unchanged. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - location to hold the method - - - - location to hold the uri - - - - location to hold the version - - - - - - Parse the response message @msg and store the values @code, @reason and -@version. The result locations can be %NULL if one is not interested in its -value. - -@reason remains valid for as long as @msg is valid and unchanged. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - location to hold the status code - - - - location to hold the status reason - - - - location to hold the version - - - - - - Remove the @indx header with key @field from @msg. If @indx equals -1, all -headers will be removed. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - the index of the header - - - - - - Remove the @index header with key @header from @msg. If @index equals -1, -all matching headers will be removed. - - - a #GstRTSPResult - - - - - a #GstRTSPMessage - - - - the header string - - - - the index of the header - - - - - - Set the body of @msg to a copy of @data. Any existing body or body buffer -will be replaced by the new body. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - the data - - - - - - the size of @data - - - - - - Set the body of @msg to @buffer. Any existing body or body buffer -will be replaced by the new body. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - a #GstBuffer - - - - - - Take the body of @msg and store it in @data and @size. After this method, -the body and size of @msg will be set to %NULL and 0 respectively. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - location for the data - - - - - - location for the size of @data - - - - - - Take the body of @msg and store it in @buffer. After this method, -the body and size of @msg will be set to %NULL and 0 respectively. - -If body data was set from raw memory instead of a #GstBuffer this function -will always return %NULL. The caller can check if there is a body buffer by -calling gst_rtsp_message_has_body_buffer(). - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - location for the buffer - - - - - - Set the body of @msg to @data and @size. This method takes ownership of -@data. Any existing body or body buffer will be replaced by the new body. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - the data - - - - - - the size of @data - - - - - - Set the body of @msg to @buffer. This method takes ownership of @buffer. -Any existing body or body buffer will be replaced by the new body. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - a #GstBuffer - - - - - - Add a header with key @field and @value to @msg. This function takes -ownership of @value. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - a #GstRTSPHeaderField - - - - the value of the header - - - - - - Add a header with key @header and @value to @msg. This function takes -ownership of @value, but not of @header. - - - a #GstRTSPResult. - - - - - a #GstRTSPMessage - - - - a header string - - - - the value of the header - - - - - - Unset the contents of @msg so that it becomes an uninitialized -#GstRTSPMessage again. This function is mostly used in combination with -gst_rtsp_message_init_request(), gst_rtsp_message_init_response() and -gst_rtsp_message_init_data() on stack allocated #GstRTSPMessage structures. - - - #GST_RTSP_OK. - - - - - a #GstRTSPMessage - - - - - - - The different supported RTSP methods. - - invalid method - - - the DESCRIBE method - - - the ANNOUNCE method - - - the GET_PARAMETER method - - - the OPTIONS method - - - the PAUSE method - - - the PLAY method - - - the RECORD method - - - the REDIRECT method - - - the SETUP method - - - the SET_PARAMETER method - - - the TEARDOWN method - - - the GET method (HTTP). - - - the POST method (HTTP). - - - Convert @method to a string. - - - a string representation of @method. - - - - - a #GstRTSPMethod - - - - - - - The type of a message. - - invalid message type - - - RTSP request message - - - RTSP response message - - - HTTP request message. - - - HTTP response message. - - - data message - - - - The transfer profile to use. - - invalid profile - - - the Audio/Visual profile (RFC 3551) - - - the secure Audio/Visual profile (RFC 3711) - - - the Audio/Visual profile with feedback (RFC 4585) - - - the secure Audio/Visual profile with feedback (RFC 5124) - - - - Provides helper functions to deal with time ranges. - - - minimum value of the range - - - - maximum value of the range - - - - Converts the range in-place between different types of units. -Ranges containing the special value #GST_RTSP_TIME_NOW can not be -converted as these are only valid for #GST_RTSP_RANGE_NPT. - - - %TRUE if the range could be converted - - - - - a #GstRTSPTimeRange - - - - the unit to convert the range into - - - - - - Free the memory allocated by @range. - - - - - - - a #GstRTSPTimeRange - - - - - - Retrieve the minimum and maximum values from @range converted to -#GstClockTime in @min and @max. - -A value of %GST_CLOCK_TIME_NONE will be used to signal #GST_RTSP_TIME_NOW -and #GST_RTSP_TIME_END for @min and @max respectively. - -UTC times will be converted to nanoseconds since 1900. - - - %TRUE on success. - - - - - a #GstRTSPTimeRange - - - - result minimum #GstClockTime - - - - result maximum #GstClockTime - - - - - - Parse @rangestr to a #GstRTSPTimeRange. - - - #GST_RTSP_OK on success. - - - - - a range string to parse - - - - location to hold the #GstRTSPTimeRange result - - - - - - Convert @range into a string representation. - - - The string representation of @range. g_free() after usage. - - - - - a #GstRTSPTimeRange - - - - - - - Different possible time range units. - - SMPTE timecode - - - 29.97 frames per second - - - 25 frames per second - - - Normal play time - - - Absolute time expressed as ISO 8601 timestamps - - - - Result codes from the RTSP functions. - - no error - - - some unspecified error occurred - - - invalid arguments were provided to a function - - - an operation was canceled - - - no memory was available for the operation - - - a host resolve error occurred - - - function not implemented - - - a system error occurred, errno contains more details - - - a parsing error occurred - - - windows networking could not start - - - windows networking stack has wrong version - - - end-of-file was reached - - - a network problem occurred, h_errno contains more details - - - the host is not an IP host - - - a timeout occurred - - - the tunnel GET request has been performed - - - the tunnel POST request has been performed - - - last error - - - - The different RTSP states. - - invalid state - - - initializing - - - ready for operation - - - seeking in progress - - - playing - - - recording - - - - Enumeration of rtsp status codes - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A time indication. - - - the time of the time - - - - seconds when @type is GST_RTSP_TIME_SECONDS, - GST_RTSP_TIME_UTC and GST_RTSP_TIME_FRAMES - - - - - Extra fields for a time indication. - - - frames and subframes when type in GstRTSPTime is - GST_RTSP_TIME_FRAMES - - - - year when type is GST_RTSP_TIME_UTC - - - - month when type is GST_RTSP_TIME_UTC - - - - day when type is GST_RTSP_TIME_UTC - - - - - A time range. - - - the time units used - - - - the minimum interval - - - - the maximum interval - - - - extra fields in the minimum interval (Since: 1.2) - - - - extra fields in the maximum interval (Since: 1.2) - - - - - Possible time types. - - seconds - - - now - - - end - - - frames and subframes - - - UTC time - - - - The transfer mode to use. - - invalid tansport mode - - - transfer RTP data - - - transfer RDT (RealMedia) data - - - - Provides helper functions to deal with RTSP transport strings. - - - the transport mode - - - - the tansport profile - - - - the lower transport - - - - the destination ip/hostname - - - - the source ip/hostname - - - - the number of layers - - - - if play mode was selected - - - - if record mode was selected - - - - is append mode was selected - - - - the interleave range - - - - the time to live for multicast UDP - - - - the port pair for multicast sessions - - - - the client port pair for receiving data. For TCP - based transports, applications can use this field to store the - sender and receiver ports of the client. - - - - the server port pair for receiving data. For TCP - based transports, applications can use this field to store the - sender and receiver ports of the server. - - - - the ssrc that the sender/receiver will use - - - - - - - - - Convert @transport into a string that can be used to signal the transport in -an RTSP SETUP response. - - - a string describing the RTSP transport or %NULL when the transport -is invalid. - - - - - a #GstRTSPTransport - - - - - - Free the memory used by @transport. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransport - - - - - - Get the media type of @transport. This media type is typically -used to generate #GstCaps events. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransport - - - - media type of @transport - - - - - - Initialize @transport so that it can be used. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransport - - - - - - Get the #GstElement that can handle the buffers transported over @trans. - -It is possible that there are several managers available, use @option to -selected one. - -@manager will contain an element name or %NULL when no manager is -needed/available for @trans. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransMode - - - - location to hold the result - - - - option index. - - - - - - Get the mime type of the transport mode @trans. This mime type is typically -used to generate #GstCaps events. - This functions only deals with the GstRTSPTransMode and only - returns the mime type for #GST_RTSP_PROFILE_AVP. Use - gst_rtsp_transport_get_media_type() instead. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransMode - - - - location to hold the result - - - - - - Allocate a new initialized #GstRTSPTransport. Use gst_rtsp_transport_free() -after usage. - - - a #GstRTSPResult. - - - - - location to hold the new #GstRTSPTransport - - - - - - Parse the RTSP transport string @str into @transport. - - - a #GstRTSPResult. - - - - - a transport string - - - - a #GstRTSPTransport - - - - - - - Provides helper functions to handle RTSP urls. - - - the transports allowed - - - - the family - - - - the user - - - - the password - - - - the host - - - - the port - - - - the absolute path - - - - additional query parameters - - - - Make a copy of @url. - - - a copy of @url. Free with gst_rtsp_url_free () after usage. - - - - - a #GstRTSPUrl - - - - - - Splits the path of @url on '/' boundaries, decoding the resulting components, - -The decoding performed by this routine is "URI decoding", as defined in RFC -3986, commonly known as percent-decoding. For example, a string "foo\%2fbar" -will decode to "foo/bar" -- the \%2f being replaced by the corresponding byte -with hex value 0x2f. Note that there is no guarantee that the resulting byte -sequence is valid in any given encoding. As a special case, \%00 is not -unescaped to NUL, as that would prematurely terminate the string. - -Also note that since paths usually start with a slash, the first component -will usually be the empty string. - - - %NULL-terminated array of URL components. Free with -g_strfreev() when no longer needed. - - - - - - - a #GstRTSPUrl - - - - - - Free the memory used by @url. - - - - - - - a #GstRTSPUrl - - - - - - Get the port number of @url. - - - #GST_RTSP_OK. - - - - - a #GstRTSPUrl - - - - location to hold the port - - - - - - Get a newly allocated string describing the request URI for @url. - - - a string with the request URI. g_free() after usage. - - - - - a #GstRTSPUrl - - - - - - Get a newly allocated string describing the request URI for @url -combined with the control path for @control_path - - - a string with the request URI combined with the control path. -g_free() after usage. - - - - - a #GstRTSPUrl - - - - an RTSP aggregate control path - - - - - - Set the port number in @url to @port. - - - #GST_RTSP_OK. - - - - - a #GstRTSPUrl - - - - the port - - - - - - Parse the RTSP @urlstr into a newly allocated #GstRTSPUrl. Free after usage -with gst_rtsp_url_free(). - - - a #GstRTSPResult. - - - - - the url string to parse - - - - location to hold the result. - - - - - - - The supported RTSP versions. - - unknown/invalid version - - - version 1.0 - - - version 1.1. - - - version 2.0. - - - Convert @version to a string. - - - a string representation of @version. - - - - - a #GstRTSPVersion - - - - - - - Opaque RTSP watch object that can be used for asynchronous RTSP -operations. - - - Adds a #GstRTSPWatch to a context so that it will be executed within that context. - - - the ID (greater than 0) for the watch within the GMainContext. - - - - - a #GstRTSPWatch - - - - a GMainContext (if NULL, the default context will be used) - - - - - - Get the maximum amount of bytes and messages that will be queued in @watch. -See gst_rtsp_watch_set_send_backlog(). - - - - - - - a #GstRTSPWatch - - - - maximum bytes - - - - maximum messages - - - - - - Reset @watch, this is usually called after gst_rtsp_connection_do_tunnel() -when the file descriptors of the connection might have changed. - - - - - - - a #GstRTSPWatch - - - - - - Send a @message using the connection of the @watch. If it cannot be sent -immediately, it will be queued for transmission in @watch. The contents of -@message will then be serialized and transmitted when the connection of the -@watch becomes writable. In case the @message is queued, the ID returned in -@id will be non-zero and used as the ID argument in the message_sent -callback. - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPWatch - - - - a #GstRTSPMessage - - - - location for a message ID or %NULL - - - - - - Sends @messages using the connection of the @watch. If they cannot be sent -immediately, they will be queued for transmission in @watch. The contents of -@messages will then be serialized and transmitted when the connection of the -@watch becomes writable. In case the @messages are queued, the ID returned in -@id will be non-zero and used as the ID argument in the message_sent -callback once the last message is sent. The callback will only be called -once for the last message. - - - #GST_RTSP_OK on success. - - - - - a #GstRTSPWatch - - - - the messages to send - - - - - - the number of messages to send - - - - location for a message ID or %NULL - - - - - - When @flushing is %TRUE, abort a call to gst_rtsp_watch_wait_backlog() -and make sure gst_rtsp_watch_write_data() returns immediately with -#GST_RTSP_EINTR. And empty the queue. - - - - - - - a #GstRTSPWatch - - - - new flushing state - - - - - - Set the maximum amount of bytes and messages that will be queued in @watch. -When the maximum amounts are exceeded, gst_rtsp_watch_write_data() and -gst_rtsp_watch_send_message() will return #GST_RTSP_ENOMEM. - -A value of 0 for @bytes or @messages means no limits. - - - - - - - a #GstRTSPWatch - - - - maximum bytes - - - - maximum messages - - - - - - Decreases the reference count of @watch by one. If the resulting reference -count is zero the watch and associated memory will be destroyed. - - - - - - - a #GstRTSPWatch - - - - - - Wait until there is place in the backlog queue, @timeout is reached -or @watch is set to flushing. - -If @timeout is %NULL this function can block forever. If @timeout -contains a valid timeout, this function will return %GST_RTSP_ETIMEOUT -after the timeout expired. - -The typically use of this function is when gst_rtsp_watch_write_data -returns %GST_RTSP_ENOMEM. The caller then calls this function to wait for -free space in the backlog queue and try again. - - - %GST_RTSP_OK when if there is room in queue. - %GST_RTSP_ETIMEOUT when @timeout was reached. - %GST_RTSP_EINTR when @watch is flushing - %GST_RTSP_EINVAL when called with invalid parameters. - - - - - a #GstRTSPWatch - - - - a GTimeVal timeout - - - - - - Wait until there is place in the backlog queue, @timeout is reached -or @watch is set to flushing. - -If @timeout is 0 this function can block forever. If @timeout -contains a valid timeout, this function will return %GST_RTSP_ETIMEOUT -after the timeout expired. - -The typically use of this function is when gst_rtsp_watch_write_data -returns %GST_RTSP_ENOMEM. The caller then calls this function to wait for -free space in the backlog queue and try again. - - - %GST_RTSP_OK when if there is room in queue. - %GST_RTSP_ETIMEOUT when @timeout was reached. - %GST_RTSP_EINTR when @watch is flushing - %GST_RTSP_EINVAL when called with invalid parameters. - - - - - a #GstRTSPWatch - - - - a timeout in microseconds - - - - - - Write @data using the connection of the @watch. If it cannot be sent -immediately, it will be queued for transmission in @watch. The contents of -@message will then be serialized and transmitted when the connection of the -@watch becomes writable. In case the @message is queued, the ID returned in -@id will be non-zero and used as the ID argument in the message_sent -callback. - -This function will take ownership of @data and g_free() it after use. - -If the amount of queued data exceeds the limits set with -gst_rtsp_watch_set_send_backlog(), this function will return -#GST_RTSP_ENOMEM. - - - #GST_RTSP_OK on success. #GST_RTSP_ENOMEM when the backlog limits -are reached. #GST_RTSP_EINTR when @watch was flushing. - - - - - a #GstRTSPWatch - - - - the data to queue - - - - - - the size of @data - - - - location for a message ID or %NULL - - - - - - Create a watch object for @conn. The functions provided in @funcs will be -called with @user_data when activity happened on the watch. - -The new watch is usually created so that it can be attached to a -maincontext with gst_rtsp_watch_attach(). - -@conn must exist for the entire lifetime of the watch. - - - a #GstRTSPWatch that can be used for asynchronous RTSP -communication. Free with gst_rtsp_watch_unref () after usage. - - - - - a #GstRTSPConnection - - - - watch functions - - - - user data to pass to @funcs - - - - notify when @user_data is not referenced anymore - - - - - - - Callback functions from a #GstRTSPWatch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Macro that checks the return value of @stmt and jumps to @label when it does -not equal #GST_RTSP_OK. - - - - a statement - - - a label - - - - - The default RTSP port to connect to. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Free a %NULL-terminated array of credentials returned from -gst_rtsp_message_parse_auth_credentials(). - - - - - - - a %NULL-terminated array of #GstRTSPAuthCredential - - - - - - Accept a new connection on @socket and create a new #GstRTSPConnection for -handling communication on new socket. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a socket - - - - storage for a #GstRTSPConnection - - - - a #GCancellable to cancel the operation - - - - - - Create a newly allocated #GstRTSPConnection from @url and store it in @conn. -The connection will not yet attempt to connect to @url, use -gst_rtsp_connection_connect(). - -A copy of @url will be made. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a #GstRTSPUrl - - - - storage for a #GstRTSPConnection - - - - - - Create a new #GstRTSPConnection for handling communication on the existing -socket @socket. The @initial_buffer contains zero terminated data already -read from @socket which should be used before starting to read new data. - - - #GST_RTSP_OK when @conn contains a valid connection. - - - - - a #GSocket - - - - the IP address of the other end - - - - the port used by the other end - - - - data already read from @fd - - - - storage for a #GstRTSPConnection - - - - - - Convert @header to a #GstRTSPHeaderField. - - - a #GstRTSPHeaderField for @header or #GST_RTSP_HDR_INVALID if the -header field is unknown. - - - - - a header string - - - - - - Convert @method to a #GstRTSPMethod. - - - a #GstRTSPMethod for @method or #GST_RTSP_INVALID if the -method is unknown. - - - - - a method - - - - - - Calculates the digest auth response from the values given by the server and -the username and password. See RFC2069 for details. - -Currently only supported algorithm "md5". - - - Authentication response or %NULL if unsupported - - - - - Hash algorithm to use, or %NULL for MD5 - - - - Request method, e.g. PLAY - - - - Realm - - - - Username - - - - Password - - - - Original request URI - - - - Nonce - - - - - - Calculates the digest auth response from the values given by the server and -the md5sum. See RFC2069 for details. - -This function is useful when the passwords are not stored in clear text, -but instead in the same format as the .htdigest file. - -Currently only supported algorithm "md5". - - - Authentication response or %NULL if unsupported - - - - - Hash algorithm to use, or %NULL for MD5 - - - - Request method, e.g. PLAY - - - - The md5 sum of username:realm:password - - - - Original request URI - - - - Nonce - - - - - - Check whether @field may appear multiple times in a message. - - - %TRUE if multiple headers are allowed. - - - - - a #GstRTSPHeaderField - - - - - - Convert @field to a string. - - - a string representation of @field. - - - - - a #GstRTSPHeaderField - - - - - - Create a new initialized #GstRTSPMessage. Free with gst_rtsp_message_free(). - - - a #GstRTSPResult. - - - - - a location for the new #GstRTSPMessage - - - - - - Create a new data #GstRTSPMessage with @channel and store the -result message in @msg. Free with gst_rtsp_message_free(). - - - a #GstRTSPResult. - - - - - a location for the new #GstRTSPMessage - - - - the channel - - - - - - Create a new #GstRTSPMessage with @method and @uri and store the result -request message in @msg. Free with gst_rtsp_message_free(). - - - a #GstRTSPResult. - - - - - a location for the new #GstRTSPMessage - - - - the request method to use - - - - the uri of the request - - - - - - Create a new response #GstRTSPMessage with @code and @reason and store the -result message in @msg. Free with gst_rtsp_message_free(). - -When @reason is %NULL, the default reason for @code will be used. - -When @request is not %NULL, the relevant headers will be copied to the new -response message. - - - a #GstRTSPResult. - - - - - a location for the new #GstRTSPMessage - - - - the status code - - - - the status reason or %NULL - - - - the request that triggered the response or %NULL - - - - - - Convert @method to a string. - - - a string representation of @method. - - - - - a #GstRTSPMethod - - - - - - Convert @options to a string. - - - a new string of @options. g_free() after usage. - - - - - one or more #GstRTSPMethod - - - - - - Convert the comma separated list @options to a #GstRTSPMethod bitwise or -of methods. This functions is the reverse of gst_rtsp_options_as_text(). - - - a #GstRTSPMethod - - - - - a comma separated list of options - - - - - - Converts the range in-place between different types of units. -Ranges containing the special value #GST_RTSP_TIME_NOW can not be -converted as these are only valid for #GST_RTSP_RANGE_NPT. - - - %TRUE if the range could be converted - - - - - a #GstRTSPTimeRange - - - - the unit to convert the range into - - - - - - Free the memory allocated by @range. - - - - - - - a #GstRTSPTimeRange - - - - - - Retrieve the minimum and maximum values from @range converted to -#GstClockTime in @min and @max. - -A value of %GST_CLOCK_TIME_NONE will be used to signal #GST_RTSP_TIME_NOW -and #GST_RTSP_TIME_END for @min and @max respectively. - -UTC times will be converted to nanoseconds since 1900. - - - %TRUE on success. - - - - - a #GstRTSPTimeRange - - - - result minimum #GstClockTime - - - - result maximum #GstClockTime - - - - - - Parse @rangestr to a #GstRTSPTimeRange. - - - #GST_RTSP_OK on success. - - - - - a range string to parse - - - - location to hold the #GstRTSPTimeRange result - - - - - - Convert @range into a string representation. - - - The string representation of @range. g_free() after usage. - - - - - a #GstRTSPTimeRange - - - - - - Convert @code to a string. - - - a string representation of @code. - - - - - a #GstRTSPStatusCode - - - - - - Convert @result in a human readable string. - - - a newly allocated string. g_free() after usage. - - - - - a #GstRTSPResult - - - - - - Get the #GstElement that can handle the buffers transported over @trans. - -It is possible that there are several managers available, use @option to -selected one. - -@manager will contain an element name or %NULL when no manager is -needed/available for @trans. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransMode - - - - location to hold the result - - - - option index. - - - - - - Get the mime type of the transport mode @trans. This mime type is typically -used to generate #GstCaps events. - This functions only deals with the GstRTSPTransMode and only - returns the mime type for #GST_RTSP_PROFILE_AVP. Use - gst_rtsp_transport_get_media_type() instead. - - - #GST_RTSP_OK. - - - - - a #GstRTSPTransMode - - - - location to hold the result - - - - - - Allocate a new initialized #GstRTSPTransport. Use gst_rtsp_transport_free() -after usage. - - - a #GstRTSPResult. - - - - - location to hold the new #GstRTSPTransport - - - - - - Parse the RTSP transport string @str into @transport. - - - a #GstRTSPResult. - - - - - a transport string - - - - a #GstRTSPTransport - - - - - - Parse the RTSP @urlstr into a newly allocated #GstRTSPUrl. Free after usage -with gst_rtsp_url_free(). - - - a #GstRTSPResult. - - - - - the url string to parse - - - - location to hold the result. - - - - - - Convert @version to a string. - - - a string representation of @version. - - - - - a #GstRTSPVersion - - - - - - Create a watch object for @conn. The functions provided in @funcs will be -called with @user_data when activity happened on the watch. - -The new watch is usually created so that it can be attached to a -maincontext with gst_rtsp_watch_attach(). - -@conn must exist for the entire lifetime of the watch. - - - a #GstRTSPWatch that can be used for asynchronous RTSP -communication. Free with gst_rtsp_watch_unref () after usage. - - - - - a #GstRTSPConnection - - - - watch functions - - - - user data to pass to @funcs - - - - notify when @user_data is not referenced anymore - - - - - - diff --git a/gir-files/GstRtspServer-1.0.gir b/gir-files/GstRtspServer-1.0.gir deleted file mode 100644 index 45d07c35e..000000000 --- a/gir-files/GstRtspServer-1.0.gir +++ /dev/null @@ -1,12228 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An address - - - the #GstRTSPAddressPool owner of this address - - - - the address - - - - the port number - - - - number of ports - - - - TTL or 0 for unicast addresses - - - - - - - Make a copy of @addr. - - - a copy of @addr. - - - - - a #GstRTSPAddress - - - - - - Free @addr and releasing it back into the pool when owned by a -pool. - - - - - - - a #GstRTSPAddress - - - - - - - Flags used to control allocation of addresses - - - no flags - - - an IPv4 address - - - and IPv6 address - - - address with an even port - - - a multicast address - - - a unicast address - - - - An address pool, all member are private - - - Make a new #GstRTSPAddressPool. - - - a new #GstRTSPAddressPool - - - - - Take an address and ports from @pool. @flags can be used to control the -allocation. @n_ports consecutive ports will be allocated of which the first -one can be found in @port. - - - a #GstRTSPAddress that should be freed with -gst_rtsp_address_free after use or %NULL when no address could be -acquired. - - - - - a #GstRTSPAddressPool - - - - flags - - - - the amount of ports - - - - - - Adds the addresses from @min_addess to @max_address (inclusive) -to @pool. The valid port range for the addresses will be from @min_port to -@max_port inclusive. - -When @ttl is 0, @min_address and @max_address should be unicast addresses. -@min_address and @max_address can be set to -#GST_RTSP_ADDRESS_POOL_ANY_IPV4 or #GST_RTSP_ADDRESS_POOL_ANY_IPV6 to bind -to all available IPv4 or IPv6 addresses. - -When @ttl > 0, @min_address and @max_address should be multicast addresses. - - - %TRUE if the addresses could be added. - - - - - a #GstRTSPAddressPool - - - - a minimum address to add - - - - a maximum address to add - - - - the minimum port - - - - the maximum port - - - - a TTL or 0 for unicast addresses - - - - - - Clear all addresses in @pool. There should be no outstanding -allocations. - - - - - - - a #GstRTSPAddressPool - - - - - - Dump the free and allocated addresses to stdout. - - - - - - - a #GstRTSPAddressPool - - - - - - Used to know if the pool includes any unicast addresses. - - - %TRUE if the pool includes any unicast addresses, %FALSE otherwise - - - - - a #GstRTSPAddressPool - - - - - - Take a specific address and ports from @pool. @n_ports consecutive -ports will be allocated of which the first one can be found in -@port. - -If @ttl is 0, @address should be a unicast address. If @ttl > 0, @address -should be a valid multicast address. - - - #GST_RTSP_ADDRESS_POOL_OK if an address was reserved. The address -is returned in @address and should be freed with gst_rtsp_address_free -after use. - - - - - a #GstRTSPAddressPool - - - - The IP address to reserve - - - - The first port to reserve - - - - The number of ports - - - - The requested ttl - - - - storage for a #GstRTSPAddress - - - - - - the parent GObject - - - - - - - - - - - - - Opaque Address pool class. - - - - - - - - - - - - - - - Result codes from RTSP address pool functions. - - - no error - - - invalid arguments were provided to a function - - - the addres has already been reserved - - - the address is not in the pool - - - last error - - - - The authentication structure. - - - Create a new #GstRTSPAuth instance. - - - a new #GstRTSPAuth - - - - - Check if @check is allowed in the current context. - - - FALSE if check failed. - - - - - the item to check - - - - - - Construct a Basic authorisation token from @user and @pass. - - - the base64 encoding of the string @user:@pass. -g_free() after usage. - - - - - a userid - - - - a password - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Add a basic token for the default authentication algorithm that -enables the client with privileges listed in @token. - - - - - - - a #GstRTSPAuth - - - - the basic token - - - - authorisation token - - - - - - Add a digest @user and @pass for the default authentication algorithm that -enables the client with privileges listed in @token. - - - - - - - a #GstRTSPAuth - - - - the digest user name - - - - the digest password - - - - authorisation token - - - - - - Get the default token for @auth. This token will be used for unauthenticated -users. - - - the #GstRTSPToken of @auth. gst_rtsp_token_unref() after -usage. - - - - - a #GstRTSPAuth - - - - - - - - the @realm of @auth - - - - - - - - - - Gets the supported authentication methods of @auth. - - - The supported authentication methods - - - - - a #GstRTSPAuth - - - - - - Get the #GTlsAuthenticationMode. - - - the #GTlsAuthenticationMode. - - - - - a #GstRTSPAuth - - - - - - Get the #GTlsCertificate used for negotiating TLS @auth. - - - the #GTlsCertificate of @auth. g_object_unref() after -usage. - - - - - a #GstRTSPAuth - - - - - - Get the #GTlsDatabase used for verifying client certificate. - - - the #GTlsDatabase of @auth. g_object_unref() after -usage. - - - - - a #GstRTSPAuth - - - - - - Parse the contents of the file at @path and enable the privileges -listed in @token for the users it describes. - -The format of the file is expected to match the format described by -<https://en.wikipedia.org/wiki/Digest_access_authentication#The_.htdigest_file>, -as output by the `htdigest` command. - - - %TRUE if the file was successfully parsed, %FALSE otherwise. - - - - - - - - Path to the htdigest file - - - - authorisation token - - - - - - Removes @basic authentication token. - - - - - - - a #GstRTSPAuth - - - - the basic token - - - - - - Removes a digest user. - - - - - - - a #GstRTSPAuth - - - - the digest user name - - - - - - Set the default #GstRTSPToken to @token in @auth. The default token will -be used for unauthenticated users. - - - - - - - a #GstRTSPAuth - - - - a #GstRTSPToken - - - - - - Set the @realm of @auth - - - - - - - - - - - - - - - Sets the supported authentication @methods for @auth. - - - - - - - a #GstRTSPAuth - - - - supported methods - - - - - - The #GTlsAuthenticationMode to set on the underlying GTlsServerConnection. -When set to another value than %G_TLS_AUTHENTICATION_NONE, -#GstRTSPAuth::accept-certificate signal will be emitted and must be handled. - - - - - - - a #GstRTSPAuth - - - - a #GTlsAuthenticationMode - - - - - - Set the TLS certificate for the auth. Client connections will only -be accepted when TLS is negotiated. - - - - - - - a #GstRTSPAuth - - - - a #GTlsCertificate - - - - - - Sets the certificate database that is used to verify peer certificates. -If set to %NULL (the default), then peer certificate validation will always -set the %G_TLS_CERTIFICATE_UNKNOWN_CA error. - - - - - - - a #GstRTSPAuth - - - - a #GTlsDatabase - - - - - - - - - - - - - - - - - Emitted during the TLS handshake after the client certificate has -been received. See also gst_rtsp_auth_set_tls_authentication_mode(). - - %TRUE to accept @peer_cert (which will also -immediately end the signal emission). %FALSE to allow the signal -emission to continue, which will cause the handshake to fail if -no one else overrides it. - - - - - a #GTlsConnection - - - - the peer's #GTlsCertificate - - - - the problems with @peer_cert. - - - - - - - The authentication class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The client object represents the connection and its state with a client. - - - Create a new #GstRTSPClient instance. - - - a new #GstRTSPClient - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Attaches @client to @context. When the mainloop for @context is run, the -client will be dispatched. When @context is %NULL, the default context will be -used). - -This function should be called when the client properties and urls are fully -configured and the client is ready to start. - - - the ID (greater than 0) for the source within the GMainContext. - - - - - a #GstRTSPClient - - - - a #GMainContext - - - - - - Close the connection of @client and remove all media it was managing. - - - - - - - a #GstRTSPClient - - - - - - Get the #GstRTSPAuth used as the authentication manager of @client. - - - the #GstRTSPAuth of @client. -g_object_unref() after usage. - - - - - a #GstRTSPClient - - - - - - Get the #GstRTSPConnection of @client. - - - the #GstRTSPConnection of @client. -The connection object returned remains valid until the client is freed. - - - - - a #GstRTSPClient - - - - - - Get the Content-Length limit of @client. - - - the Content-Length limit. - - - - - a #GstRTSPClient - - - - - - Get the #GstRTSPMountPoints object that @client uses to manage its sessions. - - - a #GstRTSPMountPoints, unref after usage. - - - - - a #GstRTSPClient - - - - - - Get the #GstRTSPSessionPool object that @client uses to manage its sessions. - - - a #GstRTSPSessionPool, unref after usage. - - - - - a #GstRTSPClient - - - - - - This is useful when providing a send function through -gst_rtsp_client_set_send_func() when doing RTSP over TCP: -the send function must call gst_rtsp_stream_transport_message_sent () -on the appropriate transport when data has been received for streaming -to continue. - - - the #GstRTSPStreamTransport associated with @channel. - - - - - - - - - - - - - Get the #GstRTSPThreadPool used as the thread pool of @client. - - - the #GstRTSPThreadPool of @client. g_object_unref() after -usage. - - - - - a #GstRTSPClient - - - - - - Let the client handle @message. - - - a #GstRTSPResult. - - - - - a #GstRTSPClient - - - - an #GstRTSPMessage - - - - - - Send a message message to the remote end. @message must be a -#GST_RTSP_MESSAGE_REQUEST or a #GST_RTSP_MESSAGE_RESPONSE. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPSession to send - the message to or %NULL - - - - The #GstRTSPMessage to send - - - - - - Call @func for each session managed by @client. The result value of @func -determines what happens to the session. @func will be called with @client -locked so no further actions on @client can be performed from @func. - -If @func returns #GST_RTSP_FILTER_REMOVE, the session will be removed from -@client. - -If @func returns #GST_RTSP_FILTER_KEEP, the session will remain in @client. - -If @func returns #GST_RTSP_FILTER_REF, the session will remain in @client but -will also be added with an additional ref to the result #GList of this -function.. - -When @func is %NULL, #GST_RTSP_FILTER_REF will be assumed for each session. - - - a #GList with all -sessions for which @func returned #GST_RTSP_FILTER_REF. After usage, each -element in the #GList should be unreffed before the list is freed. - - - - - - - a #GstRTSPClient - - - - a callback - - - - user data passed to @func - - - - - - configure @auth to be used as the authentication manager of @client. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPAuth - - - - - - Set the #GstRTSPConnection of @client. This function takes ownership of -@conn. - - - %TRUE on success. - - - - - a #GstRTSPClient - - - - a #GstRTSPConnection - - - - - - Configure @client to use the specified Content-Length limit. - -Define an appropriate request size limit and reject requests exceeding the -limit with response status 413 Request Entity Too Large - - - - - - - a #GstRTSPClient - - - - Content-Length limit - - - - - - Set @mounts as the mount points for @client which it will use to map urls -to media streams. These mount points are usually inherited from the server that -created the client but can be overriden later. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPMountPoints - - - - - - Set @func as the callback that will be called when a new message needs to be -sent to the client. @user_data is passed to @func and @notify is called when -@user_data is no longer in use. - -By default, the client will send the messages on the #GstRTSPConnection that -was configured with gst_rtsp_client_attach() was called. - -It is only allowed to set either a `send_func` or a `send_messages_func` -but not both at the same time. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPClientSendFunc - - - - user data passed to @func - - - - called when @user_data is no longer in use - - - - - - Set @func as the callback that will be called when new messages needs to be -sent to the client. @user_data is passed to @func and @notify is called when -@user_data is no longer in use. - -By default, the client will send the messages on the #GstRTSPConnection that -was configured with gst_rtsp_client_attach() was called. - -It is only allowed to set either a `send_func` or a `send_messages_func` -but not both at the same time. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPClientSendMessagesFunc - - - - user data passed to @func - - - - called when @user_data is no longer in use - - - - - - Set @pool as the sessionpool for @client which it will use to find -or allocate sessions. the sessionpool is usually inherited from the server -that created the client but can be overridden later. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPSessionPool - - - - - - configure @pool to be used as the thread pool of @client. - - - - - - - a #GstRTSPClient - - - - a #GstRTSPThreadPool - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstRTSPContext - - - - - - - a newly allocated string with comma-separated list of - unsupported options. An empty string must be returned if - all options are supported. - - - - - a #GstRTSPContext - - - - a NULL-terminated array of strings - - - - - - - - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - a #GstRTSPStatusCode, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - The session - - - - The message - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - - - - - a #GstRTSPContext - - - - - - - The client class structure. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This callback is called when @client wants to send @message. When @close is -%TRUE, the connection should be closed when the message has been sent. - - - %TRUE on success. - - - - - a #GstRTSPClient - - - - a #GstRTSPMessage - - - - close the connection - - - - user data when registering the callback - - - - - - This callback is called when @client wants to send @messages. When @close is -%TRUE, the connection should be closed when the message has been sent. - - - %TRUE on success. - - - - - a #GstRTSPClient - - - - #GstRTSPMessage - - - - number of messages - - - - close the connection - - - - user data when registering the callback - - - - - - This function will be called by the gst_rtsp_client_session_filter(). An -implementation should return a value of #GstRTSPFilterResult. - -When this function returns #GST_RTSP_FILTER_REMOVE, @sess will be removed -from @client. - -A return value of #GST_RTSP_FILTER_KEEP will leave @sess untouched in -@client. - -A value of #GST_RTSP_FILTER_REF will add @sess to the result #GList of -gst_rtsp_client_session_filter(). - - - a #GstRTSPFilterResult. - - - - - a #GstRTSPClient object - - - - a #GstRTSPSession in @client - - - - user data that has been given to gst_rtsp_client_session_filter() - - - - - - Information passed around containing the context of a request. - - - the server - - - - the connection - - - - the client - - - - the complete request - - - - the complete url parsed from @request - - - - the parsed method of @uri - - - - the current auth object or %NULL - - - - authorisation token - - - - the session, can be %NULL - - - - the session media for the url can be %NULL - - - - the media factory for the url, can be %NULL - - - - the media for the url can be %NULL - - - - the stream for the url can be %NULL - - - - the response - - - - the stream transport, can be %NULL - - - - - - - - - Pops @ctx off the context stack (verifying that @ctx -is on the top of the stack). - - - - - - - a #GstRTSPContext - - - - - - Pushes @ctx onto the context stack. The current -context can then be received using gst_rtsp_context_get_current(). - - - - - - - a #GstRTSPContext - - - - - - Get the current #GstRTSPContext. This object is retrieved from the -current thread that is handling the request for a client. - - - a #GstRTSPContext - - - - - - Possible return values for gst_rtsp_session_pool_filter(). - - - Remove session - - - Keep session in the pool - - - Ref session in the result list - - - - Function registered with gst_rtsp_stream_transport_set_keepalive() and called -when the stream is active. - - - - - - - user data - - - - - - A class that contains the GStreamer element along with a list of -#GstRTSPStream objects that can produce data. - -This object is usually created from a #GstRTSPMediaFactory. - - - Create a new #GstRTSPMedia instance. @element is the bin element that -provides the different streams. The #GstRTSPMedia object contains the -element to produce RTP data for one or more related (audio/video/..) -streams. - -Ownership is taken of @element. - - - a new #GstRTSPMedia object. - - - - - a #GstElement - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Configure an SDP on @media for receiving streams - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Prepare @media for streaming. This function will create the objects -to manage the streaming. A pipeline must have been set on @media with -gst_rtsp_media_take_pipeline(). - -It will preroll the pipeline and collect vital information about the streams -such as the duration. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPThread to run the - bus handler or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Add @media specific info to @sdp. @info is used to configure the connection -information in the SDP. - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - a #GstSDPInfo - - - - - - Suspend @media. The state of the pipeline managed by @media is set to -GST_STATE_NULL but all streams are kept. @media can be prepared again -with gst_rtsp_media_unsuspend() - -@media must be prepared with gst_rtsp_media_prepare(); - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - - - - - - - - - - - - - - - Unprepare @media. After this call, the media should be prepared again before -it can be used again. If the media is set to be non-reusable, a new instance -must be created. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - - - - - - - - - - - - Unsuspend @media if it was in a suspended state. This method does nothing -when the media was not in the suspended state. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - Find all payloader elements, they should be named pay\%d in the -element of @media, and create #GstRTSPStreams for them. - -Collect all dynamic elements, named dynpay\%d, and add them to -the list of dynamic elements. - -Find all depayloader elements, they should be named depay\%d in the -element of @media, and create #GstRTSPStreams for them. - - - - - - - a #GstRTSPMedia - - - - - - Add a receiver and sender parts to the pipeline based on the transport from -SETUP. - - - %TRUE if the media pipeline has been sucessfully updated. - - - - - a #GstRTSPMedia - - - - a list of #GstRTSPTransport - - - - - - - - Create a new stream in @media that provides RTP data on @pad. -@pad should be a pad of an element inside @media->element. - - - a new #GstRTSPStream that remains valid for as long -as @media exists. - - - - - a #GstRTSPMedia - - - - a #GstElement - - - - a #GstPad - - - - - - Find a stream in @media with @control as the control uri. - - - the #GstRTSPStream with -control uri @control or %NULL when a stream with that control did -not exist. - - - - - a #GstRTSPMedia - - - - the control of the stream - - - - - - Get the #GstRTSPAddressPool used as the address pool of @media. - - - the #GstRTSPAddressPool of @media. -g_object_unref() after usage. - - - - - a #GstRTSPMedia - - - - - - Get the base_time that is used by the pipeline in @media. - -@media must be prepared before this method returns a valid base_time. - - - the base_time used by @media. - - - - - a #GstRTSPMedia - - - - - - Get the kernel UDP buffer size. - - - the kernel UDP buffer size. - - - - - a #GstRTSPMedia - - - - - - Get the clock that is used by the pipeline in @media. - -@media must be prepared before this method returns a valid clock object. - - - the #GstClock used by @media. unref after usage. - - - - - a #GstRTSPMedia - - - - - - - - Whether retransmission requests will be sent - - - - - - - - - - Get the configured DSCP QoS of attached media. - - - the DSCP QoS value of attached streams or -1 if disabled. - - - - - a #GstRTSPMedia - - - - - - Get the element that was used when constructing @media. - - - a #GstElement. Unref after usage. - - - - - a #GstRTSPMedia - - - - - - Get the latency that is used for receiving media. - - - latency in milliseconds - - - - - a #GstRTSPMedia - - - - - - Get the the maximum time-to-live value of outgoing multicast packets. - - - the maximum time-to-live value of outgoing multicast packets. - - - - - a #GstRTSPMedia - - - - - - Get the multicast interface used for @media. - - - the multicast interface for @media. -g_free() after usage. - - - - - a #GstRTSPMedia - - - - - - Get the permissions object from @media. - - - a #GstRTSPPermissions object, unref after usage. - - - - - a #GstRTSPMedia - - - - - - Get the allowed profiles of @media. - - - a #GstRTSPProfile - - - - - a #GstRTSPMedia - - - - - - Get the allowed protocols of @media. - - - a #GstRTSPLowerTrans - - - - - a #GstRTSPMedia - - - - - - Gets if and how the media clock should be published according to RFC7273. - - - The GstRTSPPublishClockMode - - - - - a #GstRTSPMedia - - - - - - Get the current range as a string. @media must be prepared with -gst_rtsp_media_prepare (). - - - The range as a string, g_free() after usage. - - - - - a #GstRTSPMedia - - - - for the PLAY request - - - - the unit to use for the string - - - - - - - - whether @media will follow the Rate-Control=no behaviour as specified -in the ONVIF replay spec. - - - - - - - - - - Get the rate and applied_rate of the current segment. - - - %FALSE if looking up the rate and applied rate failed. Otherwise -%TRUE is returned and @rate and @applied_rate are set to the rate and -applied_rate of the current segment. - - - - - a #GstRTSPMedia - - - - the rate of the current segment - - - - the applied_rate of the current segment - - - - - - Get the amount of time to store retransmission data. - - - the amount of time to store retransmission data. - - - - - a #GstRTSPMedia - - - - - - Get the status of @media. When @media is busy preparing, this function waits -until @media is prepared or in error. - - - the status of @media. - - - - - a #GstRTSPMedia - - - - - - Retrieve the stream with index @idx from @media. - - - the #GstRTSPStream at index -@idx or %NULL when a stream with that index did not exist. - - - - - a #GstRTSPMedia - - - - the stream index - - - - - - Get how @media will be suspended. - - - #GstRTSPSuspendMode. - - - - - a #GstRTSPMedia - - - - - - Get the #GstNetTimeProvider for the clock used by @media. The time provider -will listen on @address and @port for client time requests. - - - the #GstNetTimeProvider of @media. - - - - - a #GstRTSPMedia - - - - an address or %NULL - - - - a port or 0 - - - - - - Check if the pipeline for @media can be used for PLAY or RECORD methods. - - - The transport mode. - - - - - a #GstRTSPMedia - - - - - - Configure an SDP on @media for receiving streams - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - - - See gst_rtsp_stream_is_complete(), gst_rtsp_stream_is_sender(). - - - whether @media has at least one complete sender stream. - - - - - - - - - - Check if multicast sockets are configured to be bound to multicast addresses. - - - %TRUE if multicast sockets are configured to be bound to multicast addresses. - - - - - a #GstRTSPMedia - - - - - - Check if the pipeline for @media will send an EOS down the pipeline before -unpreparing. - - - %TRUE if the media will send EOS before unpreparing. - - - - - a #GstRTSPMedia - - - - - - - - %TRUE if @media is receive-only, %FALSE otherwise. - - - - - - - - - - Check if the pipeline for @media can be reused after an unprepare. - - - %TRUE if the media can be reused - - - - - a #GstRTSPMedia - - - - - - Check if the pipeline for @media can be shared between multiple clients. - - - %TRUE if the media can be shared between clients. - - - - - a #GstRTSPMedia - - - - - - Check if the pipeline for @media will be stopped when a client disconnects -without sending TEARDOWN. - - - %TRUE if the media will be stopped when a client disconnects - without sending TEARDOWN. - - - - - a #GstRTSPMedia - - - - - - Check if @media can provide a #GstNetTimeProvider for its pipeline clock. - -Use gst_rtsp_media_get_time_provider() to get the network clock. - - - %TRUE if @media can provide a #GstNetTimeProvider. - - - - - a #GstRTSPMedia - - - - - - Lock the entire media. This is needed by callers such as rtsp_client to -protect the media when it is shared by many clients. -The lock prevents that concurrent clients alters the shared media, -while one client already is working with it. -Typically the lock is taken in external RTSP API calls that uses shared media -such as DESCRIBE, SETUP, ANNOUNCE, TEARDOWN, PLAY, PAUSE. - -As best practice take the lock as soon as the function get hold of a shared -media object. Release the lock right before the function returns. - - - - - - - a #GstRTSPMedia - - - - - - Get the number of streams in this media. - - - The number of streams. - - - - - a #GstRTSPMedia - - - - - - Prepare @media for streaming. This function will create the objects -to manage the streaming. A pipeline must have been set on @media with -gst_rtsp_media_take_pipeline(). - -It will preroll the pipeline and collect vital information about the streams -such as the duration. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPThread to run the - bus handler or %NULL - - - - - - Seek the pipeline of @media to @range. @media must be prepared with -gst_rtsp_media_prepare(). - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPTimeRange - - - - - - Seek the pipeline of @media to @range with the given @flags. -@media must be prepared with gst_rtsp_media_prepare(). - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPTimeRange - - - - The minimal set of #GstSeekFlags to use - - - - - - Seek the pipeline of @media to @range with the given @flags and @rate, -and @trickmode_interval. -@media must be prepared with gst_rtsp_media_prepare(). -In order to perform the seek operation, the pipeline must contain all -needed transport parts (transport sinks). - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPTimeRange - - - - The minimal set of #GstSeekFlags to use - - - - the rate to use in the seek - - - - The trickmode interval to use for KEY_UNITS trick mode - - - - - - Check if the pipeline for @media seek and up to what point in time, -it can seek. - - - -1 if the stream is not seekable, 0 if seekable only to the beginning -and > 0 to indicate the longest duration between any two random access points. -%G_MAXINT64 means any value is possible. - - - - - a #GstRTSPMedia - - - - - - configure @pool to be used as the address pool of @media. - - - - - - - a #GstRTSPMedia - - - - a #GstRTSPAddressPool - - - - - - Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Set the kernel UDP buffer size. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Configure the clock used for the media. - - - - - - - a #GstRTSPMedia - - - - #GstClock to be used - - - - - - Set whether retransmission requests will be sent - - - - - - - - - - - - - - - Configure the dscp qos of attached streams to @dscp_qos. - - - - - - - a #GstRTSPMedia - - - - a new dscp qos value (0-63, or -1 to disable) - - - - - - Set or unset if an EOS event will be sent to the pipeline for @media before -it is unprepared. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Configure the latency used for receiving media. - - - - - - - a #GstRTSPMedia - - - - latency in milliseconds - - - - - - Set the maximum time-to-live value of outgoing multicast packets. - - - %TRUE if the requested ttl has been set successfully. - - - - - a #GstRTSPMedia - - - - the new multicast ttl value - - - - - - configure @multicast_iface to be used for @media. - - - - - - - a #GstRTSPMedia - - - - a multicast interface name - - - - - - Set @permissions on @media. - - - - - - - a #GstRTSPMedia - - - - a #GstRTSPPermissions - - - - - - Set the state of the pipeline managed by @media to @state - - - - - - - a #GstRTSPMedia - - - - the target state of the pipeline - - - - - - Configure the allowed lower transport for @media. - - - - - - - a #GstRTSPMedia - - - - the new flags - - - - - - Configure the allowed lower transport for @media. - - - - - - - a #GstRTSPMedia - - - - the new flags - - - - - - Sets if and how the media clock should be published according to RFC7273. - - - - - - - a #GstRTSPMedia - - - - the clock publish mode - - - - - - Define whether @media will follow the Rate-Control=no behaviour as specified -in the ONVIF replay spec. - - - - - - - - - - - - - - - Set the amount of time to store retransmission packets. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Set or unset if the pipeline for @media can be reused after the pipeline has -been unprepared. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Set or unset if the pipeline for @media can be shared will multiple clients. -When @shared is %TRUE, client requests for this media will share the media -pipeline. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Set the state of @media to @state and for the transports in @transports. - -@media must be prepared with gst_rtsp_media_prepare(); - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - the target state of the media - - - - -a #GPtrArray of #GstRTSPStreamTransport pointers - - - - - - - - Set or unset if the pipeline for @media should be stopped when a -client disconnects without sending TEARDOWN. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Control how @ media will be suspended after the SDP has been generated and -after a PAUSE request has been performed. - -Media must be unprepared when setting the suspend mode. - - - - - - - a #GstRTSPMedia - - - - the new #GstRTSPSuspendMode - - - - - - Sets if the media pipeline can work in PLAY or RECORD mode - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Add @media specific info to @sdp. @info is used to configure the connection -information in the SDP. - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - a #GstSDPInfo - - - - - - Suspend @media. The state of the pipeline managed by @media is set to -GST_STATE_NULL but all streams are kept. @media can be prepared again -with gst_rtsp_media_unsuspend() - -@media must be prepared with gst_rtsp_media_prepare(); - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - Set @pipeline as the #GstPipeline for @media. Ownership is -taken of @pipeline. - - - - - - - a #GstRTSPMedia - - - - a #GstPipeline - - - - - - Unlock the media. - - - - - - - a #GstRTSPMedia - - - - - - Unprepare @media. After this call, the media should be prepared again before -it can be used again. If the media is set to be non-reusable, a new instance -must be created. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - Unsuspend @media if it was in a suspended state. This method does nothing -when the media was not in the suspended state. - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - Set @media to provide a #GstNetTimeProvider. - - - - - - - a #GstRTSPMedia - - - - if a #GstNetTimeProvider should be used - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The RTSP media class - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstRTSPThread to run the - bus handler or %NULL - - - - - - - - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - - - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - - - - - %TRUE on success. - - - - - a #GstRTSPMedia - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - a #GstSDPInfo - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TRUE on success. - - - - - a #GstRTSPMedia - - - - a #GstSDPMessage - - - - - - - - - - - - - The definition and logic for constructing the pipeline for a media. The media -can contain multiple streams like audio and video. - - - Create a new #GstRTSPMediaFactory instance. - - - a new #GstRTSPMediaFactory object. - - - - - - - - - - - - - - - - - - - Construct the media object and create its streams. Implementations -should create the needed gstreamer elements and add them to the result -object. No state changes should be performed on them yet. - -One or more GstRTSPStream objects should be created from the result -with gst_rtsp_media_create_stream (). - -After the media is constructed, it can be configured and then prepared -with gst_rtsp_media_prepare (). - - - a new #GstRTSPMedia if the media could be prepared. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - Construct and return a #GstElement that is a #GstBin containing -the elements to use for streaming the media. - -The bin should contain payloaders pay\%d for each stream. The default -implementation of this function returns the bin created from the -launch parameter. - - - a new #GstElement. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A convenience method to add @role with @fieldname and additional arguments to -the permissions of @factory. If @factory had no permissions, new permissions -will be created and the role will be added to it. - - - - - - - a #GstRTSPMediaFactory - - - - a role - - - - the first field name - - - - additional arguments - - - - - - A convenience wrapper around gst_rtsp_permissions_add_role_from_structure(). -If @factory had no permissions, new permissions will be created and the -role will be added to it. - - - - - - - - - - - - - - - Construct the media object and create its streams. Implementations -should create the needed gstreamer elements and add them to the result -object. No state changes should be performed on them yet. - -One or more GstRTSPStream objects should be created from the result -with gst_rtsp_media_create_stream (). - -After the media is constructed, it can be configured and then prepared -with gst_rtsp_media_prepare (). - - - a new #GstRTSPMedia if the media could be prepared. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - Construct and return a #GstElement that is a #GstBin containing -the elements to use for streaming the media. - -The bin should contain payloaders pay\%d for each stream. The default -implementation of this function returns the bin created from the -launch parameter. - - - a new #GstElement. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - Get the #GstRTSPAddressPool used as the address pool of @factory. - - - the #GstRTSPAddressPool of @factory. g_object_unref() after -usage. - - - - - a #GstRTSPMediaFactory - - - - - - Get the kernel UDP buffer size. - - - the kernel UDP buffer size. - - - - - a #GstRTSPMedia - - - - - - Returns the clock that is going to be used by the pipelines -of all medias created from this factory. - - - The GstClock - - - - - a #GstRTSPMediaFactory - - - - - - - - Whether retransmission requests will be sent for receiving media - - - - - - - - - - Get the configured media DSCP QoS. - - - the media DSCP QoS value or -1 if disabled. - - - - - a #GstRTSPMediaFactory - - - - - - Get the latency that is used for receiving media - - - latency in milliseconds - - - - - a #GstRTSPMediaFactory - - - - - - Get the gst_parse_launch() pipeline description that will be used in the -default prepare vmethod. - - - the configured launch description. g_free() after -usage. - - - - - a #GstRTSPMediaFactory - - - - - - Get the the maximum time-to-live value of outgoing multicast packets. - - - the maximum time-to-live value of outgoing multicast packets. - - - - - a #GstRTSPMedia - - - - - - Return the GType of the GstRTSPMedia subclass this -factory will create. - - - - - - - a #GstRTSPMediaFactory - - - - - - Get the multicast interface used for @factory. - - - the multicast interface for @factory. g_free() after -usage. - - - - - a #GstRTSPMediaFactory - - - - - - Get the permissions object from @factory. - - - a #GstRTSPPermissions object, unref after usage. - - - - - a #GstRTSPMediaFactory - - - - - - Get the allowed profiles of @factory. - - - a #GstRTSPProfile - - - - - a #GstRTSPMediaFactory - - - - - - Get the allowed protocols of @factory. - - - a #GstRTSPLowerTrans - - - - - a #GstRTSPMediaFactory - - - - - - Gets if and how the media clock should be published according to RFC7273. - - - The GstRTSPPublishClockMode - - - - - a #GstRTSPMediaFactory - - - - - - Get the time that is stored for retransmission purposes - - - a #GstClockTime - - - - - a #GstRTSPMediaFactory - - - - - - Get how media created from this factory will be suspended. - - - a #GstRTSPSuspendMode. - - - - - a #GstRTSPMediaFactory - - - - - - Get if media created from this factory can be used for PLAY or RECORD -methods. - - - The transport mode. - - - - - a #GstRTSPMediaFactory - - - - - - Check if multicast sockets are configured to be bound to multicast addresses. - - - %TRUE if multicast sockets are configured to be bound to multicast addresses. - - - - - a #GstRTSPMediaFactory - - - - - - Get if media created from this factory will have an EOS event sent to the -pipeline before shutdown. - - - %TRUE if the media will receive EOS before shutdown. - - - - - a #GstRTSPMediaFactory - - - - - - Get if media created from this factory can be shared between clients. - - - %TRUE if the media will be shared between clients. - - - - - a #GstRTSPMediaFactory - - - - - - - - - - - - - - - - - configure @pool to be used as the address pool of @factory. - - - - - - - a #GstRTSPMediaFactory - - - - a #GstRTSPAddressPool - - - - - - Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - - - - - - - a #GstRTSPMediaFactory - - - - the new value - - - - - - Set the kernel UDP buffer size. - - - - - - - a #GstRTSPMedia - - - - the new value - - - - - - Configures a specific clock to be used by the pipelines -of all medias created from this factory. - - - - - - - a #GstRTSPMediaFactory - - - - the clock to be used by the media factory - - - - - - Set whether retransmission requests will be sent for -receiving media - - - - - - - - - - - - - - - Configure the media dscp qos to @dscp_qos. - - - - - - - a #GstRTSPMediaFactory - - - - a new dscp qos value (0-63, or -1 to disable) - - - - - - Configure if media created from this factory will have an EOS sent to the -pipeline before shutdown. - - - - - - - a #GstRTSPMediaFactory - - - - the new value - - - - - - Configure the latency used for receiving media - - - - - - - a #GstRTSPMediaFactory - - - - latency in milliseconds - - - - - - The gst_parse_launch() line to use for constructing the pipeline in the -default prepare vmethod. - -The pipeline description should return a GstBin as the toplevel element -which can be accomplished by enclosing the description with brackets '(' -')'. - -The description should return a pipeline with payloaders named pay0, pay1, -etc.. Each of the payloaders will result in a stream. - - - - - - - a #GstRTSPMediaFactory - - - - the launch description - - - - - - Set the maximum time-to-live value of outgoing multicast packets. - - - %TRUE if the requested ttl has been set successfully. - - - - - a #GstRTSPMedia - - - - the new multicast ttl value - - - - - - Configure the GType of the GstRTSPMedia subclass to -create (by default, overridden construct vmethods -may of course do something different) - - - - - - - a #GstRTSPMediaFactory - - - - the GType of the class to create - - - - - - configure @multicast_iface to be used for @factory. - - - - - - - a #GstRTSPMediaFactory - - - - a multicast interface name - - - - - - Set @permissions on @factory. - - - - - - - a #GstRTSPMediaFactory - - - - a #GstRTSPPermissions - - - - - - Configure the allowed profiles for @factory. - - - - - - - a #GstRTSPMediaFactory - - - - the new flags - - - - - - Configure the allowed lower transport for @factory. - - - - - - - a #GstRTSPMediaFactory - - - - the new flags - - - - - - Sets if and how the media clock should be published according to RFC7273. - - - - - - - a #GstRTSPMediaFactory - - - - the clock publish mode - - - - - - Configure the time to store for possible retransmission - - - - - - - a #GstRTSPMediaFactory - - - - a #GstClockTime - - - - - - Configure if media created from this factory can be shared between clients. - - - - - - - a #GstRTSPMediaFactory - - - - the new value - - - - - - Configure if media created from this factory should be stopped -when a client disconnects without sending TEARDOWN. - - - - - - - a #GstRTSPMediaFactory - - - - the new value - - - - - - Configure how media created from this factory will be suspended. - - - - - - - a #GstRTSPMediaFactory - - - - the new #GstRTSPSuspendMode - - - - - - Configure if this factory creates media for PLAY or RECORD modes. - - - - - - - a #GstRTSPMediaFactory - - - - the new value - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstRTSPMediaFactory class structure. - - - - - - - - - - - - - - - - - - - - - - - - - a new #GstElement. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - - - - - a new #GstRTSPMedia if the media could be prepared. - - - - - a #GstRTSPMediaFactory - - - - the url used - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A media factory that creates a pipeline to play any uri. - - - Create a new #GstRTSPMediaFactoryURI instance. - - - a new #GstRTSPMediaFactoryURI object. - - - - - Get the URI that will provide media for this factory. - - - the configured URI. g_free() after usage. - - - - - a #GstRTSPMediaFactory - - - - - - Set the URI of the resource that will be streamed by this factory. - - - - - - - a #GstRTSPMediaFactory - - - - the uri the stream - - - - - - - - - - - - - - - - - - - - - - - - The #GstRTSPMediaFactoryURI class structure. - - - - - - - - - - - - - - - - - - The state of the media pipeline. - - - media pipeline not prerolled - - - media pipeline is busy doing a clean - shutdown. - - - media pipeline is prerolling - - - media pipeline is prerolled - - - media is suspended - - - media pipeline is in error - - - - Function registered with gst_rtsp_stream_transport_set_message_sent() -and called when a message has been sent on the transport. - - - - - - - user data - - - - - - Function registered with gst_rtsp_stream_transport_set_message_sent_full() -and called when a message has been sent on the transport. - - - - - - - - - - user data - - - - - - Creates a #GstRTSPMediaFactory object for a given url. - - - Make a new mount points object. - - - a new #GstRTSPMountPoints - - - - - Make a path string from @url. - - - a path string for @url, g_free() after usage. - - - - - a #GstRTSPMountPoints - - - - a #GstRTSPUrl - - - - - - Attach @factory to the mount point @path in @mounts. - -@path is of the form (/node)+. Any previous mount point will be freed. - -Ownership is taken of the reference on @factory so that @factory should not be -used after calling this function. - - - - - - - a #GstRTSPMountPoints - - - - a mount point - - - - a #GstRTSPMediaFactory - - - - - - Make a path string from @url. - - - a path string for @url, g_free() after usage. - - - - - a #GstRTSPMountPoints - - - - a #GstRTSPUrl - - - - - - Find the factory in @mounts that has the longest match with @path. - -If @matched is %NULL, @path will match the factory exactly otherwise -the amount of characters that matched is returned in @matched. - - - the #GstRTSPMediaFactory for @path. -g_object_unref() after usage. - - - - - a #GstRTSPMountPoints - - - - a mount point - - - - the amount of @path matched - - - - - - Remove the #GstRTSPMediaFactory associated with @path in @mounts. - - - - - - - a #GstRTSPMountPoints - - - - a mount point - - - - - - - - - - - - - - - - - - The class for the media mounts object. - - - - - - - - - a path string for @url, g_free() after usage. - - - - - a #GstRTSPMountPoints - - - - a #GstRTSPUrl - - - - - - - - - - - - - - - - - - Create a new #GstRTSPOnvifClient instance. - - - a new #GstRTSPOnvifClient - - - - - - - - - - - - - - - - - - - - - - - - - - - Find the ONVIF backchannel depayloader element. It should be named -'depay_backchannel', be placed in a bin called 'onvif-backchannel' -and return all supported RTP caps on a caps query. Complete RTP caps with -at least the payload type, clock-rate and encoding-name are required. - -A new #GstRTSPStream is created for the backchannel if found. - - - %TRUE if a backchannel stream could be found and created - - - - - a #GstRTSPOnvifMedia - - - - - - Get the configured/supported bandwidth of the ONVIF backchannel pipeline in -bits per second. - - - the configured/supported backchannel bandwidth. - - - - - a #GstRTSPMedia - - - - - - Set the configured/supported bandwidth of the ONVIF backchannel pipeline in -bits per second. - - - - - - - a #GstRTSPMedia - - - - the bandwidth in bits per second - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Create a new #GstRTSPOnvifMediaFactory - - - A new #GstRTSPOnvifMediaFactory - - - - - Checks whether the client request requires backchannel. - - - %TRUE if the client request requires backchannel. - - - - - a #GstRTSPMediaFactory - - - - - - - - - Returns %TRUE if an ONVIF backchannel is supported by the media factory. - - - %TRUE if an ONVIF backchannel is supported by the media factory. - - - - - a #GstRTSPMediaFactory - - - - - - Get the configured/supported bandwidth of the ONVIF backchannel pipeline in -bits per second. - - - the configured/supported backchannel bandwidth. - - - - - a #GstRTSPMediaFactory - - - - - - Get the gst_parse_launch() pipeline description that will be used in the -default prepare vmethod for generating the ONVIF backchannel pipeline. - - - the configured backchannel launch description. g_free() after -usage. - - - - - a #GstRTSPMediaFactory - - - - - - Returns %TRUE if an ONVIF backchannel is supported by the media factory. - - - %TRUE if an ONVIF backchannel is supported by the media factory. - - - - - a #GstRTSPMediaFactory - - - - - - - - %TRUE if ONVIF replay is supported by the media factory. - - - - - - - - - - Set the configured/supported bandwidth of the ONVIF backchannel pipeline in -bits per second. - - - - - - - a #GstRTSPMediaFactory - - - - the bandwidth in bits per second - - - - - - The gst_parse_launch() line to use for constructing the ONVIF backchannel -pipeline in the default prepare vmethod if requested by the client. - -The pipeline description should return a GstBin as the toplevel element -which can be accomplished by enclosing the description with brackets '(' -')'. - -The description should return a pipeline with a single depayloader named -depay_backchannel. A caps query on the depayloader's sinkpad should return -all possible, complete RTP caps that are going to be supported. At least -the payload type, clock-rate and encoding-name need to be specified. - -Note: The pipeline part passed here must end in sinks that are not waiting -until pre-rolling before reaching the PAUSED state, i.e. setting -async=false on #GstBaseSink. Otherwise the whole media will not be able to -prepare. - - - - - - - a #GstRTSPMediaFactory - - - - the launch description - - - - - - Set to %TRUE if ONVIF replay is supported by the media factory. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if an ONVIF backchannel is supported by the media factory. - - - - - a #GstRTSPMediaFactory - - - - - - - - - - - - - - - - - - - - - Create a new #GstRTSPOnvifServer instance. - - - a new #GstRTSPOnvifServer - - - - - - - - - - - - - - - - - - - - - - - - - The opaque permissions structure. It is used to define the permissions -of objects in different roles. - - - - - - Create a new empty Authorization permissions. - - - a new empty authorization permissions. - - - - - Add a new @permission for @role to @permissions with the access in @allowed. - - - - - - - a #GstRTSPPermissions - - - - a role - - - - the permission - - - - whether the role has this permission or not - - - - - - Add a new @role to @permissions with the given variables. The fields -are the same layout as gst_structure_new(). - - - - - - - a #GstRTSPPermissions - - - - a role - - - - the first field name - - - - additional arguments - - - - - - Add a new @role to @permissions without any permissions. You can add -permissions for the role with gst_rtsp_permissions_add_permission_for_role(). - - - - - - - a #GstRTSPPermissions - - - - a role - - - - - - Add a new role to @permissions based on @structure, for example -given a role named `tester`, which should be granted a permission named -`permission1`, the structure could be created with: - -``` -gst_structure_new ("tester", "permission1", G_TYPE_BOOLEAN, TRUE, NULL); -``` - - - - - - - - - - - - - - - Add a new @role to @permissions with the given variables. Structure fields -are set according to the varargs in a manner similar to gst_structure_new(). - - - - - - - a #GstRTSPPermissions - - - - a role - - - - the first field name - - - - additional fields to add - - - - - - Get all permissions for @role in @permissions. - - - the structure with permissions for @role. It -remains valid for as long as @permissions is valid. - - - - - a #GstRTSPPermissions - - - - a role - - - - - - Check if @role in @permissions is given permission for @permission. - - - %TRUE if @role is allowed @permission. - - - - - a #GstRTSPPermissions - - - - a role - - - - a permission - - - - - - Remove all permissions for @role in @permissions. - - - - - - - a #GstRTSPPermissions - - - - a role - - - - - - - Whether the clock and possibly RTP/clock offset should be published according to RFC7273. - - Publish nothing - - - Publish the clock but not the offset - - - Publish the clock and offset - - - - Function registered with gst_rtsp_stream_transport_set_callbacks() and -called when @buffer must be sent on @channel. - - - %TRUE on success - - - - - a #GstBuffer - - - - a channel - - - - user data - - - - - - Function registered with gst_rtsp_stream_transport_set_callbacks() and -called when @buffer_list must be sent on @channel. - - - %TRUE on success - - - - - a #GstBufferList - - - - a channel - - - - user data - - - - - - This object listens on a port, creates and manages the clients connected to -it. - - - Create a new #GstRTSPServer instance. - - - a new #GstRTSPServer - - - - - A default #GSocketSourceFunc that creates a new #GstRTSPClient to accept and handle a -new connection on @socket or @server. - - - TRUE if the source could be connected, FALSE if an error occurred. - - - - - a #GSocket - - - - the condition on @source - - - - a #GstRTSPServer - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Attaches @server to @context. When the mainloop for @context is run, the -server will be dispatched. When @context is %NULL, the default context will be -used). - -This function should be called when the server properties and urls are fully -configured and the server is ready to start. - -This takes a reference on @server until the source is destroyed. Note that -if @context is not the default main context as returned by -g_main_context_default() (or %NULL), g_source_remove() cannot be used to -destroy the source. In that case it is recommended to use -gst_rtsp_server_create_source() and attach it to @context manually. - - - the ID (greater than 0) for the source within the GMainContext. - - - - - a #GstRTSPServer - - - - a #GMainContext - - - - - - Call @func for each client managed by @server. The result value of @func -determines what happens to the client. @func will be called with @server -locked so no further actions on @server can be performed from @func. - -If @func returns #GST_RTSP_FILTER_REMOVE, the client will be removed from -@server. - -If @func returns #GST_RTSP_FILTER_KEEP, the client will remain in @server. - -If @func returns #GST_RTSP_FILTER_REF, the client will remain in @server but -will also be added with an additional ref to the result #GList of this -function.. - -When @func is %NULL, #GST_RTSP_FILTER_REF will be assumed for each client. - - - a #GList with all -clients for which @func returned #GST_RTSP_FILTER_REF. After usage, each -element in the #GList should be unreffed before the list is freed. - - - - - - - a #GstRTSPServer - - - - a callback - - - - user data passed to @func - - - - - - Create a #GSocket for @server. The socket will listen on the -configured service. - - - the #GSocket for @server or %NULL when an error -occurred. - - - - - a #GstRTSPServer - - - - a #GCancellable - - - - - - Create a #GSource for @server. The new source will have a default -#GSocketSourceFunc of gst_rtsp_server_io_func(). - -@cancellable if not %NULL can be used to cancel the source, which will cause -the source to trigger, reporting the current condition (which is likely 0 -unless cancellation happened at the same time as a condition change). You can -check for this in the callback using g_cancellable_is_cancelled(). - -This takes a reference on @server until @source is destroyed. - - - the #GSource for @server or %NULL when an error -occurred. Free with g_source_unref () - - - - - a #GstRTSPServer - - - - a #GCancellable or %NULL. - - - - - - Get the address on which the server will accept connections. - - - the server address. g_free() after usage. - - - - - a #GstRTSPServer - - - - - - Get the #GstRTSPAuth used as the authentication manager of @server. - - - the #GstRTSPAuth of @server. g_object_unref() after -usage. - - - - - a #GstRTSPServer - - - - - - The maximum amount of queued requests for the server. - - - the server backlog. - - - - - a #GstRTSPServer - - - - - - Get the port number where the server was bound to. - - - the port number - - - - - a #GstRTSPServer - - - - - - Get the Content-Length limit of @server. - - - the Content-Length limit. - - - - - a #GstRTSPServer - - - - - - Get the #GstRTSPMountPoints used as the mount points of @server. - - - the #GstRTSPMountPoints of @server. g_object_unref() after -usage. - - - - - a #GstRTSPServer - - - - - - Get the service on which the server will accept connections. - - - the service. use g_free() after usage. - - - - - a #GstRTSPServer - - - - - - Get the #GstRTSPSessionPool used as the session pool of @server. - - - the #GstRTSPSessionPool used for sessions. g_object_unref() after -usage. - - - - - a #GstRTSPServer - - - - - - Get the #GstRTSPThreadPool used as the thread pool of @server. - - - the #GstRTSPThreadPool of @server. g_object_unref() after -usage. - - - - - a #GstRTSPServer - - - - - - Configure @server to accept connections on the given address. - -This function must be called before the server is bound. - - - - - - - a #GstRTSPServer - - - - the address - - - - - - configure @auth to be used as the authentication manager of @server. - - - - - - - a #GstRTSPServer - - - - a #GstRTSPAuth - - - - - - configure the maximum amount of requests that may be queued for the -server. - -This function must be called before the server is bound. - - - - - - - a #GstRTSPServer - - - - the backlog - - - - - - Define an appropriate request size limit and reject requests exceeding the -limit. - - - - - - - a #GstRTSPServer -Configure @server to use the specified Content-Length limit. - - - - - - - - - configure @mounts to be used as the mount points of @server. - - - - - - - a #GstRTSPServer - - - - a #GstRTSPMountPoints - - - - - - Configure @server to accept connections on the given service. -@service should be a string containing the service name (see services(5)) or -a string containing a port number between 1 and 65535. - -When @service is set to "0", the server will listen on a random free -port. The actual used port can be retrieved with -gst_rtsp_server_get_bound_port(). - -This function must be called before the server is bound. - - - - - - - a #GstRTSPServer - - - - the service - - - - - - configure @pool to be used as the session pool of @server. - - - - - - - a #GstRTSPServer - - - - a #GstRTSPSessionPool - - - - - - configure @pool to be used as the thread pool of @server. - - - - - - - a #GstRTSPServer - - - - a #GstRTSPThreadPool - - - - - - Take an existing network socket and use it for an RTSP connection. This -is used when transferring a socket from an HTTP server which should be used -as an RTSP over HTTP tunnel. The @initial_buffer contains any remaining data -that the HTTP server read from the socket while parsing the HTTP header. - - - TRUE if all was ok, FALSE if an error occurred. - - - - - a #GstRTSPServer - - - - a network socket - - - - the IP address of the remote client - - - - the port used by the other end - - - - any initial data that was already read from the socket - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The RTSP server class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function will be called by the gst_rtsp_server_client_filter(). An -implementation should return a value of #GstRTSPFilterResult. - -When this function returns #GST_RTSP_FILTER_REMOVE, @client will be removed -from @server. - -A return value of #GST_RTSP_FILTER_KEEP will leave @client untouched in -@server. - -A value of #GST_RTSP_FILTER_REF will add @client to the result #GList of -gst_rtsp_server_client_filter(). - - - a #GstRTSPFilterResult. - - - - - a #GstRTSPServer object - - - - a #GstRTSPClient in @server - - - - user data that has been given to gst_rtsp_server_client_filter() - - - - - - - - - Session information kept by the server for a specific client. -One client session, identified with a session id, can handle multiple medias -identified with the url of a media. - - - Create a new #GstRTSPSession instance with @sessionid. - - - a new #GstRTSPSession - - - - - a session id - - - - - - Allow @session to expire. This method must be called an equal -amount of time as gst_rtsp_session_prevent_expire(). - - - - - - - a #GstRTSPSession - - - - - - Call @func for each media in @sess. The result value of @func determines -what happens to the media. @func will be called with @sess -locked so no further actions on @sess can be performed from @func. - -If @func returns #GST_RTSP_FILTER_REMOVE, the media will be removed from -@sess. - -If @func returns #GST_RTSP_FILTER_KEEP, the media will remain in @sess. - -If @func returns #GST_RTSP_FILTER_REF, the media will remain in @sess but -will also be added with an additional ref to the result #GList of this -function.. - -When @func is %NULL, #GST_RTSP_FILTER_REF will be assumed for all media. - - - a GList with all -media for which @func returned #GST_RTSP_FILTER_REF. After usage, each -element in the #GList should be unreffed before the list is freed. - - - - - - - a #GstRTSPSession - - - - a callback - - - - user data passed to @func - - - - - - Get the string that can be placed in the Session header field. - - - the Session header of @session. -g_free() after usage. - - - - - a #GstRTSPSession - - - - - - Get the session media for @path. @matched will contain the number of matched -characters of @path. - - - the configuration for @path in @sess. - - - - - a #GstRTSPSession - - - - the path for the media - - - - the amount of matched characters - - - - - - Get the sessionid of @session. - - - the sessionid of @session. -The value remains valid as long as @session is alive. - - - - - a #GstRTSPSession - - - - - - Get the timeout value of @session. - - - the timeout of @session in seconds. - - - - - a #GstRTSPSession - - - - - - Check if @session timeout out. - Use gst_rtsp_session_is_expired_usec() instead. - - - %TRUE if @session timed out - - - - - a #GstRTSPSession - - - - the current system time - - - - - - Check if @session timeout out. - - - %TRUE if @session timed out - - - - - a #GstRTSPSession - - - - the current monotonic time - - - - - - Manage the media object @obj in @sess. @path will be used to retrieve this -media from the session with gst_rtsp_session_get_media(). - -Ownership is taken from @media. - - - a new @GstRTSPSessionMedia object. - - - - - a #GstRTSPSession - - - - the path for the media - - - - a #GstRTSPMedia - - - - - - Get the amount of milliseconds till the session will expire. - Use gst_rtsp_session_next_timeout_usec() instead. - - - the amount of milliseconds since the session will time out. - - - - - a #GstRTSPSession - - - - the current system time - - - - - - Get the amount of milliseconds till the session will expire. - - - the amount of milliseconds since the session will time out. - - - - - a #GstRTSPSession - - - - the current monotonic time - - - - - - Prevent @session from expiring. - - - - - - - a #GstRTSPSession - - - - - - Release the managed @media in @sess, freeing the memory allocated by it. - - - %TRUE if there are more media session left in @sess. - - - - - a #GstRTSPSession - - - - a #GstRTSPMedia - - - - - - Configure @session for a timeout of @timeout seconds. The session will be -cleaned up when there is no activity for @timeout seconds. - - - - - - - a #GstRTSPSession - - - - the new timeout - - - - - - Update the last_access time of the session to the current time. - - - - - - - a #GstRTSPSession - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function will be called by the gst_rtsp_session_filter(). An -implementation should return a value of #GstRTSPFilterResult. - -When this function returns #GST_RTSP_FILTER_REMOVE, @media will be removed -from @sess. - -A return value of #GST_RTSP_FILTER_KEEP will leave @media untouched in -@sess. - -A value of GST_RTSP_FILTER_REF will add @media to the result #GList of -gst_rtsp_session_filter(). - - - a #GstRTSPFilterResult. - - - - - a #GstRTSPSession object - - - - a #GstRTSPSessionMedia in @sess - - - - user data that has been given to gst_rtsp_session_filter() - - - - - - State of a client session regarding a specific media identified by path. - - - Create a new #GstRTSPSessionMedia that manages the streams -in @media for @path. @media should be prepared. - -Ownership is taken of @media. - - - a new #GstRTSPSessionMedia. - - - - - the path - - - - the #GstRTSPMedia - - - - - - Fill @range with the next available min and max channels for -interleaved transport. - - - %TRUE on success. - - - - - a #GstRTSPSessionMedia - - - - a #GstRTSPRange - - - - - - Get the base_time of the #GstRTSPMedia in @media - - - the base_time of the media. - - - - - a #GstRTSPSessionMedia - - - - - - Get the #GstRTSPMedia that was used when constructing @media - - - the #GstRTSPMedia of @media. -Remains valid as long as @media is valid. - - - - - a #GstRTSPSessionMedia - - - - - - Retrieve the RTP-Info header string for all streams in @media -with configured transports. - - - The RTP-Info as a string or -%NULL when no RTP-Info could be generated, g_free() after usage. - - - - - a #GstRTSPSessionMedia - - - - - - Get the current RTSP state of @media. - - - the current RTSP state of @media. - - - - - a #GstRTSPSessionMedia - - - - - - Get a previously created #GstRTSPStreamTransport for the stream at @idx. - - - a #GstRTSPStreamTransport that is -valid until the session of @media is unreffed. - - - - - a #GstRTSPSessionMedia - - - - the stream index - - - - - - Get a list of all available #GstRTSPStreamTransport in this session. - - - a -list of #GstRTSPStreamTransport, g_ptr_array_unref () after usage. - - - - - - - a #GstRTSPSessionMedia - - - - - - Check if the path of @media matches @path. It @path matches, the amount of -matched characters is returned in @matched. - - - %TRUE when @path matches the path of @media. - - - - - a #GstRTSPSessionMedia - - - - a path - - - - the amount of matched characters of @path - - - - - - Set the RTSP state of @media to @state. - - - - - - - a #GstRTSPSessionMedia - - - - a #GstRTSPState - - - - - - Tell the media object @media to change to @state. - - - %TRUE on success. - - - - - a #GstRTSPSessionMedia - - - - the new state - - - - - - Configure the transport for @stream to @tr in @media. - - - the new or updated #GstRTSPStreamTransport for @stream. - - - - - a #GstRTSPSessionMedia - - - - a #GstRTSPStream - - - - a #GstRTSPTransport - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An object that keeps track of the active sessions. This object is usually -attached to a #GstRTSPServer object to manage the sessions in that server. - - - Create a new #GstRTSPSessionPool instance. - - - A new #GstRTSPSessionPool. g_object_unref() after -usage. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Inspect all the sessions in @pool and remove the sessions that are inactive -for more than their timeout. - - - the amount of sessions that got removed. - - - - - a #GstRTSPSessionPool - - - - - - Create a new #GstRTSPSession object in @pool. - - - a new #GstRTSPSession. - - - - - a #GstRTSPSessionPool - - - - - - Create a #GSource that will be dispatched when the session should be cleaned -up. - - - a #GSource - - - - - a #GstRTSPSessionPool - - - - - - Call @func for each session in @pool. The result value of @func determines -what happens to the session. @func will be called with the session pool -locked so no further actions on @pool can be performed from @func. - -If @func returns #GST_RTSP_FILTER_REMOVE, the session will be set to the -expired state and removed from @pool. - -If @func returns #GST_RTSP_FILTER_KEEP, the session will remain in @pool. - -If @func returns #GST_RTSP_FILTER_REF, the session will remain in @pool but -will also be added with an additional ref to the result GList of this -function.. - -When @func is %NULL, #GST_RTSP_FILTER_REF will be assumed for all sessions. - - - a GList with all -sessions for which @func returned #GST_RTSP_FILTER_REF. After usage, each -element in the GList should be unreffed before the list is freed. - - - - - - - a #GstRTSPSessionPool - - - - a callback - - - - user data passed to @func - - - - - - Find the session with @sessionid in @pool. The access time of the session -will be updated with gst_rtsp_session_touch(). - - - the #GstRTSPSession with @sessionid -or %NULL when the session did not exist. g_object_unref() after usage. - - - - - the pool to search - - - - the session id - - - - - - Get the maximum allowed number of sessions in @pool. 0 means an unlimited -amount of sessions. - - - the maximum allowed number of sessions. - - - - - a #GstRTSPSessionPool - - - - - - Get the amount of active sessions in @pool. - - - the amount of active sessions in @pool. - - - - - a #GstRTSPSessionPool - - - - - - Remove @sess from @pool, releasing the ref that the pool has on @sess. - - - %TRUE if the session was found and removed. - - - - - a #GstRTSPSessionPool - - - - a #GstRTSPSession - - - - - - Configure the maximum allowed number of sessions in @pool to @max. -A value of 0 means an unlimited amount of sessions. - - - - - - - a #GstRTSPSessionPool - - - - the maximum number of sessions - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This function will be called by the gst_rtsp_session_pool_filter(). An -implementation should return a value of #GstRTSPFilterResult. - -When this function returns #GST_RTSP_FILTER_REMOVE, @session will be removed -from @pool. - -A return value of #GST_RTSP_FILTER_KEEP will leave @session untouched in -@pool. - -A value of GST_RTSP_FILTER_REF will add @session to the result #GList of -gst_rtsp_session_pool_filter(). - - - a #GstRTSPFilterResult. - - - - - a #GstRTSPSessionPool object - - - - a #GstRTSPSession in @pool - - - - user data that has been given to gst_rtsp_session_pool_filter() - - - - - - The function that will be called from the GSource watch on the session pool. - -The function will be called when the pool must be cleaned up because one or -more sessions timed out. - - - %FALSE if the source should be removed. - - - - - a #GstRTSPSessionPool object - - - - user data that has been given when registering the handler - - - - - - - - - - - - The definition of a media stream. - - - Create a new media stream with index @idx that handles RTP data on -@pad and has a payloader element @payloader if @pad is a source pad -or a depayloader element @payloader if @pad is a sink pad. - - - a new #GstRTSPStream - - - - - an index - - - - a #GstElement - - - - a #GstPad - - - - - - Add multicast client address to stream. At this point, the sockets that -will stream RTP and RTCP data to @destination are supposed to be -allocated. - - - %TRUE if @destination can be addedd and handled by @stream. - - - - - a #GstRTSPStream - - - - a multicast address to add - - - - RTP port - - - - RTCP port - - - - socket family - - - - - - Add the transport in @trans to @stream. The media of @stream will -then also be send to the values configured in @trans. Adding the -same transport twice will not add it a second time. - -@stream must be joined to a bin. - -@trans must contain a valid #GstRTSPTransport. - - - %TRUE if @trans was added - - - - - a #GstRTSPStream - - - - a #GstRTSPStreamTransport - - - - - - Allocates RTP and RTCP ports. - - - %TRUE if the RTP and RTCP sockets have been succeccully allocated. - - - - - a #GstRTSPStream - - - - protocol family - - - - transport method - - - - Whether to use client settings or not - - - - - - Add a receiver and sender part to the pipeline based on the transport from -SETUP. - - - %TRUE if the stream has been sucessfully updated. - - - - - a #GstRTSPStream - - - - a #GstRTSPTransport - - - - - - Get the #GstRTSPAddressPool used as the address pool of @stream. - - - the #GstRTSPAddressPool of @stream. -g_object_unref() after usage. - - - - - a #GstRTSPStream - - - - - - Get the size of the UDP transmission buffer (in bytes) - - - the size of the UDP TX buffer - - - - - a #GstRTSPStream - - - - - - Retrieve the current caps of @stream. - - - the #GstCaps of @stream. -use gst_caps_unref() after usage. - - - - - a #GstRTSPStream - - - - - - Get the control string to identify this stream. - - - the control string. g_free() after usage. - - - - - a #GstRTSPStream - - - - - - - - - - - - - - - - - Get the configured DSCP QoS in of the outgoing sockets. - - - the DSCP QoS value of the outgoing sockets, or -1 if disbled. - - - - - a #GstRTSPStream - - - - - - Get the stream index. - - - the stream index. - - - - - a #GstRTSPStream - - - - - - Get the previous joined bin with gst_rtsp_stream_join_bin() or NULL. - - - the joined bin or NULL. - - - - - a #GstRTSPStream - - - - - - Get the the maximum time-to-live value of outgoing multicast packets. - - - the maximum time-to-live value of outgoing multicast packets. - - - - - a #GstRTSPStream - - - - - - Get the configured MTU in the payloader of @stream. - - - the MTU of the payloader. - - - - - a #GstRTSPStream - - - - - - Get the multicast address of @stream for @family. The original -#GstRTSPAddress is cached and copy is returned, so freeing the return value -won't release the address from the pool. - - - the #GstRTSPAddress of @stream -or %NULL when no address could be allocated. gst_rtsp_address_free() -after usage. - - - - - a #GstRTSPStream - - - - the #GSocketFamily - - - - - - Get all multicast client addresses that RTP data will be sent to - - - A comma separated list of host:port pairs with destinations - - - - - a #GstRTSPStream - - - - - - Get the multicast interface used for @stream. - - - the multicast interface for @stream. -g_free() after usage. - - - - - a #GstRTSPStream - - - - - - Get the allowed profiles of @stream. - - - a #GstRTSPProfile - - - - - a #GstRTSPStream - - - - - - Get the allowed protocols of @stream. - - - a #GstRTSPLowerTrans - - - - - a #GstRTSPStream - - - - - - Get the stream payload type. - - - the stream payload type. - - - - - a #GstRTSPStream - - - - - - Gets if and how the stream clock should be published according to RFC7273. - - - The GstRTSPPublishClockMode - - - - - a #GstRTSPStream - - - - - - - - whether @stream will follow the Rate-Control=no behaviour as specified -in the ONVIF replay spec. - - - - - - - - - - Retrieve the current rate and/or applied_rate. - - - %TRUE if rate and/or applied_rate could be determined. - - - - - a #GstRTSPStream - - - - the configured rate - - - - the configured applied_rate - - - - - - Get the payload-type used for retransmission of this stream - - - The retransmission PT. - - - - - a #GstRTSPStream - - - - - - Get the amount of time to store retransmission data. - - - the amount of time to store retransmission data. - - - - - a #GstRTSPStream - - - - - - Get the multicast RTCP socket from @stream for a @family. - - - the multicast RTCP socket or %NULL if no -socket could be allocated for @family. Unref after usage - - - - - a #GstRTSPStream - - - - the socket family - - - - - - Get the RTCP socket from @stream for a @family. - -@stream must be joined to a bin. - - - the RTCP socket or %NULL if no -socket could be allocated for @family. Unref after usage - - - - - a #GstRTSPStream - - - - the socket family - - - - - - Get the multicast RTP socket from @stream for a @family. - - - the multicast RTP socket or %NULL if no - -socket could be allocated for @family. Unref after usage - - - - - a #GstRTSPStream - - - - the socket family - - - - - - Get the RTP socket from @stream for a @family. - -@stream must be joined to a bin. - - - the RTP socket or %NULL if no -socket could be allocated for @family. Unref after usage - - - - - a #GstRTSPStream - - - - the socket family - - - - - - Retrieve the current rtptime, seq and running-time. This is used to -construct a RTPInfo reply header. - - - %TRUE when rtptime, seq and running-time could be determined. - - - - - a #GstRTSPStream - - - - result RTP timestamp - - - - result RTP seqnum - - - - the clock rate - - - - result running-time - - - - - - Get the RTP session of this stream. - - - The RTP session of this stream. Unref after usage. - - - - - a #GstRTSPStream - - - - - - Fill @server_port with the port pair used by the server. This function can -only be called when @stream has been joined. - - - - - - - a #GstRTSPStream - - - - result server port - - - - the port family to get - - - - - - Get the sinkpad associated with @stream. - - - the sinkpad. Unref after usage. - - - - - a #GstRTSPStream - - - - - - Get the srcpad associated with @stream. - - - the srcpad. Unref after usage. - - - - - a #GstRTSPStream - - - - - - Get the SRTP encoder for this stream. - - - The SRTP encoder for this stream. Unref after usage. - - - - - a #GstRTSPStream - - - - - - Get the SSRC used by the RTP session of this stream. This function can only -be called when @stream has been joined. - - - - - - - a #GstRTSPStream - - - - result ssrc - - - - - - - - - - - - - - - - - - - the amount of redundancy applied when creating ULPFEC -protection packets. - - - - - - - - - - - - the payload type used for ULPFEC protection packets - - - - - - - - - - Parse and handle a KeyMgmt header. - - - - - - - a #GstRTSPStream - - - - a keymgmt header - - - - - - Check if @stream has the control string @control. - - - %TRUE is @stream has @control as the control string - - - - - a #GstRTSPStream - - - - a control string - - - - - - Check if multicast sockets are configured to be bound to multicast addresses. - - - %TRUE if multicast sockets are configured to be bound to multicast addresses. - - - - - a #GstRTSPStream - - - - - - Check if @stream is blocking on a #GstBuffer. - - - %TRUE if @stream is blocking - - - - - a #GstRTSPStream - - - - - - See gst_rtsp_stream_set_client_side() - - - TRUE if this #GstRTSPStream is client-side. - - - - - a #GstRTSPStream - - - - - - Checks whether the stream is complete, contains the receiver and the sender -parts. As the stream contains sink(s) element(s), it's possible to perform -seek operations on it. - - - %TRUE if the stream contains at least one sink element. - - - - - a #GstRTSPStream - - - - - - Checks whether the stream is a receiver. - - - %TRUE if the stream is a receiver and %FALSE otherwise. - - - - - a #GstRTSPStream - - - - - - Checks whether the stream is a sender. - - - %TRUE if the stream is a sender and %FALSE otherwise. - - - - - a #GstRTSPStream - - - - - - Check if @transport can be handled by stream - - - %TRUE if @transport can be handled by @stream. - - - - - a #GstRTSPStream - - - - a #GstRTSPTransport - - - - - - Join the #GstBin @bin that contains the element @rtpbin. - -@stream will link to @rtpbin, which must be inside @bin. The elements -added to @bin will be set to the state given in @state. - - - %TRUE on success. - - - - - a #GstRTSPStream - - - - a #GstBin to join - - - - a rtpbin element in @bin - - - - the target state of the new elements - - - - - - Remove the elements of @stream from @bin. - - - %TRUE on success. - - - - - a #GstRTSPStream - - - - a #GstBin - - - - a rtpbin #GstElement - - - - - - Query the position of the stream in %GST_FORMAT_TIME. This only considers -the RTP parts of the pipeline and not the RTCP parts. - - - %TRUE if the position could be queried - - - - - a #GstRTSPStream - - - - current position of a #GstRTSPStream - - - - - - Query the stop of the stream in %GST_FORMAT_TIME. This only considers -the RTP parts of the pipeline and not the RTCP parts. - - - %TRUE if the stop could be queried - - - - - a #GstRTSPStream - - - - current stop of a #GstRTSPStream - - - - - - Handle an RTCP buffer for the stream. This method is usually called when a -message has been received from a client using the TCP transport. - -This function takes ownership of @buffer. - - - a GstFlowReturn. - - - - - a #GstRTSPStream - - - - a #GstBuffer - - - - - - Handle an RTP buffer for the stream. This method is usually called when a -message has been received from a client using the TCP transport. - -This function takes ownership of @buffer. - - - a GstFlowReturn. - - - - - a #GstRTSPStream - - - - a #GstBuffer - - - - - - Remove the transport in @trans from @stream. The media of @stream will -not be sent to the values configured in @trans. - -@stream must be joined to a bin. - -@trans must contain a valid #GstRTSPTransport. - - - %TRUE if @trans was removed - - - - - a #GstRTSPStream - - - - a #GstRTSPStreamTransport - - - - - - Creating a rtxreceive bin - - - a #GstElement. - - - - - a #GstRTSPStream - - - - the session id - - - - - - Creating a rtxsend bin - - - a #GstElement. - - - - - a #GstRTSPStream - - - - the session id - - - - - - Creating a rtpulpfecdec element - - - a #GstElement. - - - - - - - - - - - - - - - - Creating a rtpulpfecenc element - - - a #GstElement. - - - - - - - - - - - - - Reserve @address and @port as the address and port of @stream. The original -#GstRTSPAddress is cached and copy is returned, so freeing the return value -won't release the address from the pool. - - - the #GstRTSPAddress of @stream or %NULL when -the address could not be reserved. gst_rtsp_address_free() after -usage. - - - - - a #GstRTSPStream - - - - an address - - - - a port - - - - n_ports - - - - a TTL - - - - - - Checks whether the individual @stream is seekable. - - - %TRUE if @stream is seekable, else %FALSE. - - - - - a #GstRTSPStream - - - - - - configure @pool to be used as the address pool of @stream. - - - - - - - a #GstRTSPStream - - - - a #GstRTSPAddressPool - - - - - - Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - - - - - - - a #GstRTSPStream, - - - - the new value - - - - - - Blocks or unblocks the dataflow on @stream. - - - %TRUE on success - - - - - a #GstRTSPStream - - - - boolean indicating we should block or unblock - - - - - - Set the size of the UDP transmission buffer (in bytes) -Needs to be set before the stream is joined to a bin. - - - - - - - a #GstRTSPStream - - - - the buffer size - - - - - - Sets the #GstRTSPStream as a 'client side' stream - used for sending -streams to an RTSP server via RECORD. This has the practical effect -of changing which UDP port numbers are used when setting up the local -side of the stream sending to be either the 'server' or 'client' pair -of a configured UDP transport. - - - - - - - a #GstRTSPStream - - - - TRUE if this #GstRTSPStream is running on the 'client' side of -an RTSP connection. - - - - - - Set the control string in @stream. - - - - - - - a #GstRTSPStream - - - - a control string - - - - - - Configure the dscp qos of the outgoing sockets to @dscp_qos. - - - - - - - a #GstRTSPStream - - - - a new dscp qos value (0-63, or -1 to disable) - - - - - - Set the maximum time-to-live value of outgoing multicast packets. - - - %TRUE if the requested ttl has been set successfully. - - - - - a #GstRTSPStream - - - - the new multicast ttl value - - - - - - Configure the mtu in the payloader of @stream to @mtu. - - - - - - - a #GstRTSPStream - - - - a new MTU - - - - - - configure @multicast_iface to be used for @stream. - - - - - - - a #GstRTSPStream - - - - a multicast interface name - - - - - - Configure the allowed profiles for @stream. - - - - - - - a #GstRTSPStream - - - - the new profiles - - - - - - Configure the allowed lower transport for @stream. - - - - - - - a #GstRTSPStream - - - - the new flags - - - - - - Configure a pt map between @pt and @caps. - - - - - - - a #GstRTSPStream - - - - the pt - - - - a #GstCaps - - - - - - Sets if and how the stream clock should be published according to RFC7273. - - - - - - - a #GstRTSPStream - - - - the clock publish mode - - - - - - Define whether @stream will follow the Rate-Control=no behaviour as specified -in the ONVIF replay spec. - - - - - - - - - - - - - - - Set the payload type (pt) for retransmission of this stream. - - - - - - - a #GstRTSPStream - - - - a #guint - - - - - - Set the amount of time to store retransmission packets. - - - - - - - a #GstRTSPStream - - - - a #GstClockTime - - - - - - - - - - - - - - - - - - - - Sets the amount of redundancy to apply when creating ULPFEC -protection packets. - - - - - - - - - - - - - - - Set the payload type to be used for ULPFEC protection packets - - - - - - - - - - - - - - - Call @func for each transport managed by @stream. The result value of @func -determines what happens to the transport. @func will be called with @stream -locked so no further actions on @stream can be performed from @func. - -If @func returns #GST_RTSP_FILTER_REMOVE, the transport will be removed from -@stream. - -If @func returns #GST_RTSP_FILTER_KEEP, the transport will remain in @stream. - -If @func returns #GST_RTSP_FILTER_REF, the transport will remain in @stream but -will also be added with an additional ref to the result #GList of this -function.. - -When @func is %NULL, #GST_RTSP_FILTER_REF will be assumed for each transport. - - - a #GList with all -transports for which @func returned #GST_RTSP_FILTER_REF. After usage, each -element in the #GList should be unreffed before the list is freed. - - - - - - - a #GstRTSPStream - - - - a callback - - - - user data passed to @func - - - - - - - - - - - - - - - - - Update the new crypto information for @ssrc in @stream. If information -for @ssrc did not exist, it will be added. If information -for @ssrc existed, it will be replaced. If @crypto is %NULL, it will -be removed from @stream. - - - %TRUE if @crypto could be updated - - - - - a #GstRTSPStream - - - - the SSRC - - - - a #GstCaps with crypto info - - - - - - Check if the requested multicast ttl value is allowed. - - - TRUE if the requested ttl value is allowed. - - - - - a #GstRTSPStream - - - - a requested multicast ttl - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A Transport description for a stream - - - Create a new #GstRTSPStreamTransport that can be used to manage -@stream with transport @tr. - - - a new #GstRTSPStreamTransport - - - - - a #GstRTSPStream - - - - a GstRTSPTransport - - - - - - Get the RTP-Info string for @trans and @start_time. - - - the RTPInfo string for @trans -and @start_time or %NULL when the RTP-Info could not be -determined. g_free() after usage. - - - - - a #GstRTSPStreamTransport - - - - a star time - - - - - - Get the #GstRTSPStream used when constructing @trans. - - - the stream used when constructing @trans. - - - - - a #GstRTSPStreamTransport - - - - - - Get the transport configured in @trans. - - - the transport configured in @trans. It remains -valid for as long as @trans is valid. - - - - - a #GstRTSPStreamTransport - - - - - - Get the url configured in @trans. - - - the url configured in @trans. -It remains valid for as long as @trans is valid. - - - - - a #GstRTSPStreamTransport - - - - - - Check if @trans is timed out. - - - %TRUE if @trans timed out. - - - - - a #GstRTSPStreamTransport - - - - - - Signal the installed keep_alive callback for @trans. - - - - - - - a #GstRTSPStreamTransport - - - - - - Signal the installed message_sent / message_sent_full callback for @trans. - - - - - - - a #GstRTSPStreamTransport - - - - - - Receive @buffer on @channel @trans. - - - a #GstFlowReturn. Returns GST_FLOW_NOT_LINKED when @channel is not - configured in the transport of @trans. - - - - - a #GstRTSPStreamTransport - - - - a channel - - - - a #GstBuffer - - - - - - Send @buffer to the installed RTCP callback for @trans. - - - %TRUE on success - - - - - a #GstRTSPStreamTransport - - - - a #GstBuffer - - - - - - Send @buffer_list to the installed RTCP callback for @trans. - - - %TRUE on success - - - - - a #GstRTSPStreamTransport - - - - a #GstBuffer - - - - - - Send @buffer to the installed RTP callback for @trans. - - - %TRUE on success - - - - - a #GstRTSPStreamTransport - - - - a #GstBuffer - - - - - - Send @buffer_list to the installed RTP callback for @trans. - - - %TRUE on success - - - - - a #GstRTSPStreamTransport - - - - a #GstBufferList - - - - - - Activate or deactivate datatransfer configured in @trans. - - - %TRUE when the state was changed. - - - - - a #GstRTSPStreamTransport - - - - new state of @trans - - - - - - Install callbacks that will be called when data for a stream should be sent -to a client. This is usually used when sending RTP/RTCP over TCP. - - - - - - - a #GstRTSPStreamTransport - - - - a callback called when RTP should be sent - - - - a callback called when RTCP should be sent - - - - user data passed to callbacks - - - - called with the user_data when no longer needed. - - - - - - Install callbacks that will be called when RTCP packets are received from the -receiver of @trans. - - - - - - - a #GstRTSPStreamTransport - - - - a callback called when the receiver is active - - - - user data passed to callback - - - - called with the user_data when no longer needed. - - - - - - Install callbacks that will be called when data for a stream should be sent -to a client. This is usually used when sending RTP/RTCP over TCP. - - - - - - - a #GstRTSPStreamTransport - - - - a callback called when RTP should be sent - - - - a callback called when RTCP should be sent - - - - user data passed to callbacks - - - - called with the user_data when no longer needed. - - - - - - Install a callback that will be called when a message has been sent on @trans. - - - - - - - a #GstRTSPStreamTransport - - - - a callback called when a message has been sent - - - - user data passed to callback - - - - called with the user_data when no longer needed - - - - - - Install a callback that will be called when a message has been sent on @trans. - - - - - - - a #GstRTSPStreamTransport - - - - a callback called when a message has been sent - - - - user data passed to callback - - - - called with the user_data when no longer needed - - - - - - Set the timed out state of @trans to @timedout - - - - - - - a #GstRTSPStreamTransport - - - - timed out value - - - - - - Set @tr as the client transport. This function takes ownership of the -passed @tr. - - - - - - - a #GstRTSPStreamTransport - - - - a client #GstRTSPTransport - - - - - - Set @url as the client url. - - - - - - - a #GstRTSPStreamTransport - - - - a client #GstRTSPUrl - - - - - - parent instance - - - - - - - - - - - - - - - - - - - - - - - - This function will be called by the gst_rtsp_stream_transport_filter(). An -implementation should return a value of #GstRTSPFilterResult. - -When this function returns #GST_RTSP_FILTER_REMOVE, @trans will be removed -from @stream. - -A return value of #GST_RTSP_FILTER_KEEP will leave @trans untouched in -@stream. - -A value of #GST_RTSP_FILTER_REF will add @trans to the result #GList of -gst_rtsp_stream_transport_filter(). - - - a #GstRTSPFilterResult. - - - - - a #GstRTSPStream object - - - - a #GstRTSPStreamTransport in @stream - - - - user data that has been given to gst_rtsp_stream_transport_filter() - - - - - - - - - The suspend mode of the media pipeline. A media pipeline is suspended right -after creating the SDP and when the client performs a PAUSED request. - - Media is not suspended - - - Media is PAUSED in suspend - - - The media is set to NULL when suspended - - - - Structure holding info about a mainloop running in a thread - - - parent #GstMiniObject - - - - the thread type - - - - a #GMainContext - - - - a #GMainLoop - - - - Create a new thread object that can run a mainloop. - - - a #GstRTSPThread. - - - - - the thread type - - - - - - Reuse the mainloop of @thread - - - %TRUE if the mainloop could be reused - - - - - a #GstRTSPThread - - - - - - Stop and unref @thread. When no threads are using the mainloop, the thread -will be stopped and the final ref to @thread will be released. - - - - - - - a #GstRTSPThread - - - - - - - The thread pool structure. - - - Create a new #GstRTSPThreadPool instance. - - - a new #GstRTSPThreadPool - - - - - Wait for all tasks to be stopped and free all allocated resources. This is -mainly used in test suites to ensure proper cleanup of internal data -structures. - - - - - - - - - - - - - - - - - - - - - - - - Get a new #GstRTSPThread for @type and @ctx. - - - a new #GstRTSPThread, -gst_rtsp_thread_stop() after usage - - - - - a #GstRTSPThreadPool - - - - the #GstRTSPThreadType - - - - a #GstRTSPContext - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get the maximum number of threads used for client connections. -See gst_rtsp_thread_pool_set_max_threads(). - - - the maximum number of threads. - - - - - a #GstRTSPThreadPool - - - - - - Get a new #GstRTSPThread for @type and @ctx. - - - a new #GstRTSPThread, -gst_rtsp_thread_stop() after usage - - - - - a #GstRTSPThreadPool - - - - the #GstRTSPThreadType - - - - a #GstRTSPContext - - - - - - Set the maximum threads used by the pool to handle client requests. -A value of 0 will use the pool mainloop, a value of -1 will use an -unlimited number of threads. - - - - - - - a #GstRTSPThreadPool - - - - maximum threads - - - - - - - - - - - - - - - - - - - - - Class for managing threads. - - - - - - a #GThreadPool used internally - - - - - - - a new #GstRTSPThread, -gst_rtsp_thread_stop() after usage - - - - - a #GstRTSPThreadPool - - - - the #GstRTSPThreadType - - - - a #GstRTSPContext - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Different thread types - - - a thread to handle the client communication - - - a thread to handle media - - - - An opaque object used for checking authorisations. -It is generated after successful authentication. - - - - - - Create a new Authorization token with the given fieldnames and values. -Arguments are given similar to gst_structure_new(). - - - a new authorization token. - - - - - the first fieldname - - - - additional arguments - - - - - - Create a new empty Authorization token. - - - a new empty authorization token. - - - - - Create a new Authorization token with the given fieldnames and values. -Arguments are given similar to gst_structure_new_valist(). - - - a new authorization token. - - - - - the first fieldname - - - - additional arguments - - - - - - Get the string value of @field in @token. - - - the string value of @field in -@token or %NULL when @field is not defined in @token. The string -becomes invalid when you free @token. - - - - - a #GstRTSPToken - - - - a field name - - - - - - Access the structure of the token. - - - The structure of the token. The structure is still -owned by the token, which means that you should not free it and that the -pointer becomes invalid when you free the token. - -MT safe. - - - - - The #GstRTSPToken. - - - - - - Check if @token has a boolean @field and if it is set to %TRUE. - - - %TRUE if @token has a boolean field named @field set to %TRUE. - - - - - a #GstRTSPToken - - - - a field name - - - - - - Sets a boolean value on @token. - - - - - - - The #GstRTSPToken. - - - - field to set - - - - boolean value to set - - - - - - Sets a string value on @token. - - - - - - - The #GstRTSPToken. - - - - field to set - - - - string value to set - - - - - - Get a writable version of the structure. - - - The structure of the token. The structure is still -owned by the token, which means that you should not free it and that the -pointer becomes invalid when you free the token. This function checks if -@token is writable and will never return %NULL. - -MT safe. - - - - - The #GstRTSPToken. - - - - - - - The supported modes of the media. - - Transport supports PLAY mode - - - Transport supports RECORD mode - - - - - - - - - - - Used with gst_rtsp_address_pool_add_range() to bind to all -IPv4 addresses - - - - - Used with gst_rtsp_address_pool_add_range() to bind to all -IPv6 addresses - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Check a new connection - - - - - Check if access is allowed to a factory. -When access is not allowed an 404 Not Found is sent in the response. - - - - - Check if media can be constructed from a media factory -A response should be sent on error. - - - - - Check if the client can specify TTL, destination and -port pair in multicast. No response is sent when the check returns -%FALSE. - - - - - Check the URL and methods - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - G_TYPE_BOOLEAN, %TRUE if the media can be accessed, %FALSE will -return a 404 Not Found error when trying to access the media. - - - - - G_TYPE_BOOLEAN, %TRUE if the media can be constructed, %FALSE will -return a 404 Not Found error when trying to access the media. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - G_TYPE_STRING, the role to use when dealing with media factories - -The default #GstRTSPAuth object uses this string in the token to find the -role of the media factory. It will then retrieve the #GstRTSPPermissions of -the media factory and retrieve the role with the same name. - - - - - G_TYPE_BOOLEAN, %TRUE if the client can specify TTL, destination and - port pair in multicast. - - - - - - - - - - - - - - Get the current #GstRTSPContext. This object is retrieved from the -current thread that is handling the request for a client. - - - a #GstRTSPContext - - - - - - - - - - - Get parameters (not implemented yet) - - - a #GstRTSPResult - - - - - a #GstRTSPClient - - - - a #GstRTSPContext - - - - - - Set parameters (not implemented yet) - - - a #GstRTSPResult - - - - - a #GstRTSPClient - - - - a #GstRTSPContext - - - - - - Add @media specific info to @sdp. @info is used to configure the connection -information in the SDP. - - - TRUE on success. - - - - - a #GstSDPMessage - - - - a #GstSDPInfo - - - - a #GstRTSPMedia - - - - - - Add info from @stream to @sdp. - - - TRUE on success. - - - - - a #GstSDPMessage - - - - a #GstSDPInfo - - - - a #GstRTSPStream - - - - - - Creates a #GstSDPMedia from the parameters and stores it in @sdp. - - - %TRUE on success - - - - - a #GstRTSPMessage - - - - a #GstSDPInfo - - - - a #GstRTSPStream - - - - a #GstCaps - - - - a #GstRTSPProfile - - - - - - diff --git a/gir-files/GstSdp-1.0.gir b/gir-files/GstSdp-1.0.gir deleted file mode 100644 index 224d58a42..000000000 --- a/gir-files/GstSdp-1.0.gir +++ /dev/null @@ -1,4290 +0,0 @@ - - - - - - - - - The different cache types - - - The envelope key MUST NOT be cached - - - The envelope key MUST be cached - - - The envelope key MUST be cached, but only - to be used for the specific CSB. - - - - - - - The encryption algorithm used to encrypt the Encr data field - - - no encryption - - - AES-CM using a 128-bit key - - - AES Key Wrap using a 128-bit key - - - AES-GCM using a 128-bit key (Since: 1.16) - - - - - - - The key validity type - - - No specific usage rule - - - The key is associated with the SPI/MKI - - - The key has a start and expiration time - - - - The type of key. - - - a TEK Generation Key - - - Traffic-Encrypting Key - - - - Specifies the authentication algorithm used - - - no authentication - - - HMAC-SHA-1-160 - - - - The Security policy Map item for SRTP - - - The security policy applied for the stream with @ssrc - - - - the SSRC that must be used for the stream - - - - current rollover counter - - - - - Specifies the method of uniquely mapping Crypto Sessions to the security -protocol sessions. - - - SRTP - - - - Structure holding the information of the MIKEY message - - - - - - the version - - - - the #GstMIKEYType message type - - - - verify flag - - - - a #GstMIKEYPRFFunc - - - - Identifies the Crypto Session Bundle - - - - a #GstMIKEYMapType - - - - map info array of type depending on @map_type - - - - - - the payload array of #GstMIKEYPayload - - - - - - Make a new MIKEY message. - - - a new #GstMIKEYMessage on success - - - - - Make a new #GstMIKEYMessage from @bytes. - - - a new #GstMIKEYMessage - - - - - a #GBytes - - - - a #GstMIKEYDecryptInfo - - - - - - Makes mikey message including: - - Security Policy Payload - - Key Data Transport Payload - - Key Data Sub-Payload - - - a #GstMIKEYMessage, -or %NULL if there is no srtp information in the caps. - - - - - a #GstCaps, including SRTP parameters (srtp/srtcp cipher, authorization, key data) - - - - - - Parse @size bytes from @data into a #GstMIKEYMessage. @info contains the -parameters to decrypt and verify the data. - - - a #GstMIKEYMessage on success or %NULL when parsing failed and -@error will be set. - - - - - bytes to read - - - - - - length of @data - - - - #GstMIKEYDecryptInfo - - - - - - Add a Crypto policy for SRTP to @msg. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - The security policy applied for the stream with @ssrc - - - - the SSRC that must be used for the stream - - - - current rollover counter - - - - - - Add a new payload to @msg. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - a #GstMIKEYPayload - - - - - - Add a new PKE payload to @msg with the given parameters. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - envelope key cache indicator - - - - the length of @data - - - - the encrypted envelope key - - - - - - - - Add a new RAND payload to @msg with the given parameters. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - the length of @rand - - - - random data - - - - - - - - Add a new RAND payload to @msg with @len random bytes. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - length - - - - - - Add a new T payload to @msg with the given parameters. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - specifies the timestamp type used - - - - The timestamp value of the specified @type - - - - - - - - Add a new T payload to @msg that contains the current time -in NTP-UTC format. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - - - - - a #gchar, base64-encoded data - - - - - a #GstMIKEYMessage - - - - - - Find the @nth occurrence of the payload with @type in @msg. - - - the @nth #GstMIKEYPayload of @type. - - - - - a #GstMIKEYMessage - - - - a #GstMIKEYPayloadType - - - - payload to find - - - - - - Get the policy information of @msg at @idx. - - - a #GstMIKEYMapSRTP - - - - - a #GstMIKEYMessage - - - - an index - - - - - - Get the number of crypto sessions in @msg. - - - the number of crypto sessions - - - - - a #GstMIKEYMessage - - - - - - Get the number of payloads in @msg. - - - the number of payloads in @msg - - - - - a #GstMIKEYMessage - - - - - - Get the #GstMIKEYPayload at @idx in @msg - - - the #GstMIKEYPayload at @idx. The payload -remains valid for as long as it is part of @msg. - - - - - a #GstMIKEYMessage - - - - an index - - - - - - Insert a Crypto Session map for SRTP in @msg at @idx - -When @idx is -1, the policy will be appended. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - the index to insert at - - - - the map info - - - - - - Insert the @payload at index @idx in @msg. If @idx is -1, the payload -will be appended to @msg. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - an index - - - - a #GstMIKEYPayload - - - - - - Remove the SRTP policy at @idx. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - the index to remove - - - - - - Remove the payload in @msg at @idx - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - an index - - - - - - Replace a Crypto Session map for SRTP in @msg at @idx with @map. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - the index to insert at - - - - the map info - - - - - - Replace the payload at @idx in @msg with @payload. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - an index - - - - a #GstMIKEYPayload - - - - - - Set the information in @msg. - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - a version - - - - a #GstMIKEYType - - - - verify flag - - - - the #GstMIKEYPRFFunc function to use - - - - the Crypto Session Bundle id - - - - the #GstMIKEYMapType - - - - - - Convert @msg to a #GBytes. - - - a new #GBytes for @msg. - - - - - a #GstMIKEYMessage - - - - a #GstMIKEYEncryptInfo - - - - - - - - %TRUE on success - - - - - a #GstMIKEYMessage - - - - a #GstCaps to be filled with SRTP parameters (srtp/srtcp cipher, authorization, key data) - - - - - - - The PRF function that has been/will be used for key derivation - - - MIKEY-1 PRF function - - - - Hold the common fields for all payloads - - - - - - the payload type - - - - length of the payload - - - - Make a new #GstMIKEYPayload with @type. - - - a new #GstMIKEYPayload or %NULL on failure. - - - - - a #GstMIKEYPayloadType - - - - - - Add a new sub payload to @payload. - - - %TRUE on success. - - - - - a #GstMIKEYPayload - - - - a #GstMIKEYPayload to add - - - - - - Get the number of sub payloads of @payload. @payload should be of type -%GST_MIKEY_PT_KEMAC. - - - the number of sub payloads in @payload - - - - - a #GstMIKEYPayload - - - - - - Get the sub payload of @payload at @idx. @payload should be of type -%GST_MIKEY_PT_KEMAC. - - - the #GstMIKEYPayload at @idx. - - - - - a #GstMIKEYPayload - - - - an index - - - - - - Remove the sub payload at @idx in @payload. - - - %TRUE on success. - - - - - a #GstMIKEYPayload - - - - the index to remove - - - - - - Set the KEMAC parameters. @payload should point to a %GST_MIKEY_PT_KEMAC -payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the #GstMIKEYEncAlg - - - - a #GstMIKEYMacAlg - - - - - - Set the key validity period in the %GST_MIKEY_PT_KEY_DATA @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the length of @vf_data - - - - the Valid From data - - - - - - the length of @vt_data - - - - the Valid To data - - - - - - - - Set @key_len bytes of @key_data of type @key_type as the key for the -%GST_MIKEY_PT_KEY_DATA @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - a #GstMIKEYKeyDataType - - - - the length of @key_data - - - - the key of type @key_type - - - - - - - - Set the salt key data. If @salt_len is 0 and @salt_data is %NULL, the -salt data will be removed. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the length of @salt_data - - - - the salt - - - - - - - - Set the SPI/MKI validity in the %GST_MIKEY_PT_KEY_DATA @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the length of @spi_data - - - - the SPI/MKI data - - - - - - - - Set the PKE values in @payload. @payload must be of type -%GST_MIKEY_PT_PKE. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - envelope key cache indicator - - - - the length of @data - - - - the encrypted envelope key - - - - - - - - Set the random values in a %GST_MIKEY_PT_RAND @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the length of @rand - - - - random values - - - - - - - - Add a new parameter to the %GST_MIKEY_PT_SP @payload with @type, @len -and @val. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - a type - - - - a length - - - - @len bytes of data - - - - - - - - Get the number of security policy parameters in a %GST_MIKEY_PT_SP -@payload. - - - the number of parameters in @payload - - - - - a #GstMIKEYPayload - - - - - - Get the Security Policy parameter in a %GST_MIKEY_PT_SP @payload -at @idx. - - - the #GstMIKEYPayloadSPParam at @idx in @payload - - - - - a #GstMIKEYPayload - - - - an index - - - - - - Remove the Security Policy parameters from a %GST_MIKEY_PT_SP -@payload at @idx. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - an index - - - - - - Set the Security Policy parameters for @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the policy number - - - - a #GstMIKEYSecProto - - - - - - Set the timestamp in a %GST_MIKEY_PT_T @payload. - - - %TRUE on success - - - - - a #GstMIKEYPayload - - - - the #GstMIKEYTSType - - - - the timestamp value - - - - - - - - - A structure holding the KEMAC payload - - - the common #GstMIKEYPayload - - - - the #GstMIKEYEncAlg - - - - the #GstMIKEYMacAlg - - - - the subpayloads - - - - - - - The Key data payload contains key material. It should be added as sub -payload to the KEMAC. - - - the payload header - - - - the #GstMIKEYKeyDataType of @key_data - - - - length of @key_data - - - - the key data - - - - the length of @salt_data, can be 0 - - - - salt data - - - - the Key Validity type - - - - length of @kv_data - - - - - - key validity data - - - - - - - The Envelope data payload contains the encrypted envelope key that is -used in the public-key transport to protect the data in the Key data -transport payload. The encryption algorithm used is implicit from -the certificate/public key used. - - - the common #GstMIKEYPayload - - - - envelope key cache indicator - - - - length of @data - - - - the encrypted envelope key - - - - - The RAND payload consists of a (pseudo-)random bit-string - - - the payload header - - - - the length of @rand - - - - random values - - - - - The Security Policy payload defines a set of policies that apply to a -specific security protocol - - - the payload header - - - - the policy number - - - - the security protocol - - - - array of #GstMIKEYPayloadSPParam - - - - - - - A Type/Length/Value field for security parameters - - - specifies the type of the parameter - - - - specifies the length of @val - - - - specifies the value of the parameter - - - - - The timestamp payload carries the timestamp information - - - the payload header - - - - a #GstMIKEYTSType - - - - the timestamp value - - - - - Different MIKEY Payload types. - - - Last payload - - - Key data transport payload - - - Envelope data payload - - - DH data payload - - - Signature payload - - - Timestamp payload - - - ID payload - - - Certificate Payload - - - Cert hash payload - - - Verification message payload - - - Security Policy payload - - - RAND payload - - - Error payload - - - Key data sub-payload - - - General Extension Payload - - - - Specifies the security protocol - - - SRTP - - - - This policy specifies the parameters for SRTP and SRTCP - - - Encryption algorithm - - - Session Encr. key length - - - Authentication algorithm - - - Session Auth. key length - - - Session Salt key length - - - SRTP Pseudo Random Function - - - Key derivation rate - - - SRTP encryption off/on, 0 if off, 1 if on - - - SRTCP encryption off/on, 0 if off, 1 if on - - - sender's FEC order - - - SRTP authentication off/on, 0 if off, 1 if on - - - Authentication tag length - - - SRTP prefix length - - - AEAD authentication tag length (Since: 1.16) - - - - Specifies the timestamp type. - - - an NTP time in UTC timezone - - - an NTP time - - - a counter - - - - Different MIKEY data types. - - - Invalid type - - - Initiator's pre-shared key message - - - Verification message of a Pre-shared key message - - - Initiator's public-key transport message - - - Verification message of a public-key message - - - Initiator's DH exchange message - - - Responder's DH exchange message - - - Error message - - - - The supported MIKEY version 1. - - - - - The contents of the SDP "a=" field which contains a key/value pair. - - - the attribute key - - - - the attribute value or NULL when it was a property attribute - - - - Clear the attribute. - - - @GST_SDP_OK. - - - - - a #GstSDPAttribute - - - - - - Set the attribute with @key and @value. - - - @GST_SDP_OK. - - - - - a #GstSDPAttribute - - - - the key - - - - the value - - - - - - - The contents of the SDP "b=" field which specifies the proposed bandwidth to -be used by the session or media. - - - the bandwidth modifier type - - - - the bandwidth in kilobits per second - - - - Reset the bandwidth information in @bw. - - - a #GstSDPResult. - - - - - a #GstSDPBandwidth - - - - - - Set bandwidth information in @bw. - - - a #GstSDPResult. - - - - - a #GstSDPBandwidth - - - - the bandwidth modifier type - - - - the bandwidth in kilobits per second - - - - - - - The contents of the SDP "c=" field which contains connection data. - - - the type of network. "IN" is defined to have the meaning - "Internet". - - - - the type of @address. - - - - the address - - - - the time to live of the address - - - - the number of layers - - - - Clear the connection. - - - @GST_SDP_OK. - - - - - a #GstSDPConnection - - - - - - Set the connection with the given parameters. - - - @GST_SDP_OK. - - - - - a #GstSDPConnection - - - - the type of network. "IN" is defined to have the meaning -"Internet". - - - - the type of address. - - - - the address - - - - the time to live of the address - - - - the number of layers - - - - - - - The contents of the SDP "k=" field which is used to convey encryption -keys. - - - the encryption type - - - - the encryption data - - - - - The contents of the SDP "m=" field with all related fields. - - - the media type - - - - the transport port to which the media stream will be sent - - - - the number of ports or -1 if only one port was specified - - - - the transport protocol - - - - an array of #gchar formats - - - - - - the media title - - - - array of #GstSDPConnection with media connection information - - - - - - array of #GstSDPBandwidth with media bandwidth information - - - - - - the encryption key - - - - array of #GstSDPAttribute with the additional media attributes - - - - - - Add the attribute with @key and @value to @media. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - a key - - - - a value - - - - - - Add the bandwidth information with @bwtype and @bandwidth to @media. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the bandwidth modifier type - - - - the bandwidth in kilobits per second - - - - - - Add the given connection parameters to @media. - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - the type of network. "IN" is defined to have the meaning -"Internet". - - - - the type of address. - - - - the address - - - - the time to live of the address - - - - the number of layers - - - - - - Add the format information to @media. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the format - - - - - - Convert the contents of @media to a text string. - - - A dynamically allocated string representing the media. - - - - - a #GstSDPMedia - - - - - - Get the number of attribute fields in @media. - - - the number of attributes in @media. - - - - - a #GstSDPMedia - - - - - - Mapping of attributes of #GstSDPMedia to #GstCaps - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - a #GstCaps - - - - - - Get the number of bandwidth fields in @media. - - - the number of bandwidths in @media. - - - - - a #GstSDPMedia - - - - - - Get the number of connection fields in @media. - - - the number of connections in @media. - - - - - a #GstSDPMedia - - - - - - Allocate a new copy of @media and store the result in @copy. The value in -@copy should be release with gst_sdp_media_free function. - - - a #GstSDPResult - - - - - a #GstSDPMedia - - - - pointer to new #GstSDPMedia - - - - - - Get the number of formats in @media. - - - the number of formats in @media. - - - - - a #GstSDPMedia - - - - - - Free all resources allocated by @media. @media should not be used anymore after -this function. This function should be used when @media was dynamically -allocated with gst_sdp_media_new(). - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - - - Get the attribute at position @idx in @media. - - - the #GstSDPAttribute at position @idx. - - - - - a #GstSDPMedia - - - - an index - - - - - - Get the first attribute value for @key in @media. - - - the first attribute value for @key. - - - - - a #GstSDPMedia - - - - a key - - - - - - Get the @nth attribute value for @key in @media. - - - the @nth attribute value. - - - - - a #GstSDPMedia - - - - a key - - - - an index - - - - - - Get the bandwidth at position @idx in @media. - - - the #GstSDPBandwidth at position @idx. - - - - - a #GstSDPMedia - - - - an index - - - - - - Mapping of caps from SDP fields: - -a=rtpmap:(payload) (encoding_name)/(clock_rate)[/(encoding_params)] - -a=framesize:(payload) (width)-(height) - -a=fmtp:(payload) (param)[=(value)];... - -Note that the extmap attribute is set only by gst_sdp_media_attributes_to_caps(). - - - a #GstCaps, or %NULL if an error happened - - - - - a #GstSDPMedia - - - - a payload type - - - - - - Get the connection at position @idx in @media. - - - the #GstSDPConnection at position @idx. - - - - - a #GstSDPMedia - - - - an index - - - - - - Get the format information at position @idx in @media. - - - the format at position @idx. - - - - - a #GstSDPMedia - - - - an index - - - - - - Get the information of @media - - - the information of @media. - - - - - a #GstSDPMedia - - - - - - Get the encryption information from @media. - - - a #GstSDPKey. - - - - - a #GstSDPMedia - - - - - - Get the media description of @media. - - - the media description. - - - - - a #GstSDPMedia - - - - - - Get the number of ports for @media. - - - the number of ports for @media. - - - - - a #GstSDPMedia - - - - - - Get the port number for @media. - - - the port number of @media. - - - - - a #GstSDPMedia - - - - - - Get the transport protocol of @media - - - the transport protocol of @media. - - - - - a #GstSDPMedia - - - - - - Initialize @media so that its contents are as if it was freshly allocated -with gst_sdp_media_new(). This function is mostly used to initialize a media -allocated on the stack. gst_sdp_media_uninit() undoes this operation. - -When this function is invoked on newly allocated data (with malloc or on the -stack), its contents should be set to 0 before calling this function. - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - - - Insert the attribute to @media at @idx. When @idx is -1, -the attribute is appended. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPAttribute - - - - - - Insert the bandwidth information to @media at @idx. When @idx is -1, -the bandwidth is appended. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPBandwidth - - - - - - Insert the connection information to @media at @idx. When @idx is -1, -the connection is appended. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPConnection - - - - - - Insert the format information to @media at @idx. When @idx is -1, -the format is appended. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - the format - - - - - - Creates a new #GstMIKEYMessage after parsing the key-mgmt attribute -from a #GstSDPMedia. - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - pointer to new #GstMIKEYMessage - - - - - - Remove the attribute in @media at @idx. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - - - Remove the bandwidth information in @media at @idx. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - - - Remove the connection information in @media at @idx. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - - - Remove the format information in @media at @idx. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - - - Replace the attribute in @media at @idx with @attr. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPAttribute - - - - - - Replace the bandwidth information in @media at @idx with @bw. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPBandwidth - - - - - - Replace the connection information in @media at @idx with @conn. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - a #GstSDPConnection - - - - - - Replace the format information in @media at @idx with @format. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - an index - - - - the format - - - - - - Set the media information of @media to @information. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the media information - - - - - - Adds the encryption information to @media. - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - the encryption type - - - - the encryption data - - - - - - Set the media description of @media to @med. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the media description - - - - - - Set the port information in @media. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the port number - - - - the number of ports - - - - - - Set the media transport protocol of @media to @proto. - - - #GST_SDP_OK. - - - - - a #GstSDPMedia - - - - the media transport protocol - - - - - - Free all resources allocated in @media. @media should not be used anymore after -this function. This function should be used when @media was allocated on the -stack and initialized with gst_sdp_media_init(). - - - a #GstSDPResult. - - - - - a #GstSDPMedia - - - - - - Allocate a new GstSDPMedia and store the result in @media. - - - a #GstSDPResult. - - - - - pointer to new #GstSDPMedia - - - - - - Mapping of caps to SDP fields: - -a=rtpmap:(payload) (encoding_name) or (clock_rate)[or (encoding_params)] - -a=framesize:(payload) (width)-(height) - -a=fmtp:(payload) (param)[=(value)];... - -a=rtcp-fb:(payload) (param1) [param2]... - -a=extmap:(id)[/direction] (extensionname) (extensionattributes) - - - a #GstSDPResult. - - - - - a #GstCaps - - - - a #GstSDPMedia - - - - - - - The GstSDPMessage helper functions makes it easy to parse and create SDP -messages. - - - the protocol version - - - - owner/creator and session identifier - - - - session name - - - - session information - - - - URI of description - - - - array of #gchar with email addresses - - - - - - array of #gchar with phone numbers - - - - - - connection information for the session - - - - array of #GstSDPBandwidth with bandwidth information - - - - - - array of #GstSDPTime with time descriptions - - - - - - array of #GstSDPZone with time zone adjustments - - - - - - encryption key - - - - array of #GstSDPAttribute with session attributes - - - - - - array of #GstSDPMedia with media descriptions - - - - - - Add the attribute with @key and @value to @msg. - - - @GST_SDP_OK. - - - - - a #GstSDPMessage - - - - the key - - - - the value - - - - - - Add the specified bandwidth information to @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the bandwidth modifier type - - - - the bandwidth in kilobits per second - - - - - - Add @email to the list of emails in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an email - - - - - - Adds @media to the array of medias in @msg. This function takes ownership of -the contents of @media so that @media will have to be reinitialized with -gst_sdp_media_init() before it can be used again. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a #GstSDPMedia to add - - - - - - Add @phone to the list of phones in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a phone - - - - - - Add time information @start and @stop to @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the start time - - - - the stop time - - - - the repeat times - - - - - - - - Add time zone information to @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the NTP time that a time zone adjustment happens - - - - the offset from the time when the session was first scheduled - - - - - - Convert the contents of @msg to a text string. - - - A dynamically allocated string representing the SDP description. - - - - - a #GstSDPMessage - - - - - - Get the number of attributes in @msg. - - - the number of attributes in @msg. - - - - - a #GstSDPMessage - - - - - - Mapping of attributes of #GstSDPMessage to #GstCaps - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a #GstCaps - - - - - - Get the number of bandwidth information in @msg. - - - the number of bandwidth information in @msg. - - - - - a #GstSDPMessage - - - - - - Allocate a new copy of @msg and store the result in @copy. The value in -@copy should be release with gst_sdp_message_free function. - - - a #GstSDPResult - - - - - a #GstSDPMessage - - - - pointer to new #GstSDPMessage - - - - - - Dump the parsed contents of @msg to stdout. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get the number of emails in @msg. - - - the number of emails in @msg. - - - - - a #GstSDPMessage - - - - - - Free all resources allocated by @msg. @msg should not be used anymore after -this function. This function should be used when @msg was dynamically -allocated with gst_sdp_message_new(). - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get the attribute at position @idx in @msg. - - - the #GstSDPAttribute at position @idx. - - - - - a #GstSDPMessage - - - - the index - - - - - - Get the first attribute with key @key in @msg. - - - the attribute value of the first attribute with @key. - - - - - a #GstSDPMessage - - - - the key - - - - - - Get the @nth attribute with key @key in @msg. - - - the attribute value of the @nth attribute with @key. - - - - - a #GstSDPMessage - - - - the key - - - - the index - - - - - - Get the bandwidth at index @idx from @msg. - - - a #GstSDPBandwidth. - - - - - a #GstSDPMessage - - - - the bandwidth index - - - - - - Get the connection of @msg. - - - a #GstSDPConnection. The result remains valid as long as @msg is valid. - - - - - a #GstSDPMessage - - - - - - Get the email with number @idx from @msg. - - - the email at position @idx. - - - - - a #GstSDPMessage - - - - an email index - - - - - - Get the information in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get the encryption information from @msg. - - - a #GstSDPKey. - - - - - a #GstSDPMessage - - - - - - Get the media description at index @idx in @msg. - - - a #GstSDPMedia. - - - - - a #GstSDPMessage - - - - the index - - - - - - Get the origin of @msg. - - - a #GstSDPOrigin. The result remains valid as long as @msg is valid. - - - - - a #GstSDPMessage - - - - - - Get the phone with number @idx from @msg. - - - the phone at position @idx. - - - - - a #GstSDPMessage - - - - a phone index - - - - - - Get the session name in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get time information with index @idx from @msg. - - - a #GstSDPTime. - - - - - a #GstSDPMessage - - - - the time index - - - - - - Get the URI in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get the version in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get time zone information with index @idx from @msg. - - - a #GstSDPZone. - - - - - a #GstSDPMessage - - - - the zone index - - - - - - Initialize @msg so that its contents are as if it was freshly allocated -with gst_sdp_message_new(). This function is mostly used to initialize a message -allocated on the stack. gst_sdp_message_uninit() undoes this operation. - -When this function is invoked on newly allocated data (with malloc or on the -stack), its contents should be set to 0 before calling this function. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Insert attribute into the array of attributes in @msg -at index @idx. -When -1 is given as @idx, the attribute is inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an index - - - - a #GstSDPAttribute - - - - - - Insert bandwidth parameters into the array of bandwidths in @msg -at index @idx. -When -1 is given as @idx, the bandwidth is inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an index - - - - the bandwidth - - - - - - Insert @email into the array of emails in @msg at index @idx. -When -1 is given as @idx, the email is inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an index - - - - an email - - - - - - Insert @phone into the array of phone numbers in @msg at index @idx. -When -1 is given as @idx, the phone is inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a phone index - - - - a phone - - - - - - Insert time parameters into the array of times in @msg -at index @idx. -When -1 is given as @idx, the times are inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an index - - - - a #GstSDPTime - - - - - - Insert zone parameters into the array of zones in @msg -at index @idx. -When -1 is given as @idx, the zone is inserted at the end. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an index - - - - a #GstSDPZone - - - - - - Get the number of media descriptions in @msg. - - - the number of media descriptions in @msg. - - - - - a #GstSDPMessage - - - - - - Creates a new #GstMIKEYMessage after parsing the key-mgmt attribute -from a #GstSDPMessage. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - pointer to new #GstMIKEYMessage - - - - - - Get the number of phones in @msg. - - - the number of phones in @msg. - - - - - a #GstSDPMessage - - - - - - Remove the attribute in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - - - Remove the bandwidth information in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the bandwidth index - - - - - - Remove the email in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an email index - - - - - - Remove the phone number in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a phone index - - - - - - Remove the time information in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - - - Remove the zone information in @msg at index @idx. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - - - Replace the attribute in @msg at index @idx with @attr. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - a #GstSDPAttribute - - - - - - Replace the bandwidth information in @msg at index @idx with @bw. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the bandwidth index - - - - the bandwidth - - - - - - Replace the email in @msg at index @idx with @email. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - an email index - - - - an email - - - - - - Replace the phone number in @msg at index @idx with @phone. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - a phone index - - - - a phone - - - - - - Replace the time information in @msg at index @idx with @t. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - a #GstSDPTime - - - - - - Replace the zone information in @msg at index @idx with @zone. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the index - - - - a #GstSDPZone - - - - - - Configure the SDP connection in @msg with the given parameters. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the type of network. "IN" is defined to have the meaning -"Internet". - - - - the type of address. - - - - the address - - - - the time to live of the address - - - - the number of layers - - - - - - Set the information in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the information - - - - - - Adds the encryption information to @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the encryption type - - - - the encryption data - - - - - - Configure the SDP origin in @msg with the given parameters. - - - #GST_SDP_OK. - - - - - a #GstSDPMessage - - - - the user name - - - - a session id - - - - a session version - - - - a network type - - - - an address type - - - - an address - - - - - - Set the session name in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the session name - - - - - - Set the URI in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the URI - - - - - - Set the version in @msg. - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - the version - - - - - - Get the number of time information entries in @msg. - - - the number of time information entries in @msg. - - - - - a #GstSDPMessage - - - - - - Free all resources allocated in @msg. @msg should not be used anymore after -this function. This function should be used when @msg was allocated on the -stack and initialized with gst_sdp_message_init(). - - - a #GstSDPResult. - - - - - a #GstSDPMessage - - - - - - Get the number of time zone information entries in @msg. - - - the number of time zone information entries in @msg. - - - - - a #GstSDPMessage - - - - - - Creates a uri from @msg with the given @scheme. The uri has the format: - - \@scheme:///[#type=value *[&type=value]] - - Where each value is url encoded. - - - a uri for @msg. - - - - - the uri scheme - - - - the #GstSDPMessage - - - - - - Allocate a new GstSDPMessage and store the result in @msg. - - - a #GstSDPResult. - - - - - pointer to new #GstSDPMessage - - - - - - Parse @text and create a new SDPMessage from these. - - - a #GstSDPResult. - - - - - A dynamically allocated string representing the SDP description - - - - pointer to new #GstSDPMessage - - - - - - Parse the contents of @size bytes pointed to by @data and store the result in -@msg. - - - #GST_SDP_OK on success. - - - - - the start of the buffer - - - - - - the size of the buffer - - - - the result #GstSDPMessage - - - - - - Parse the null-terminated @uri and store the result in @msg. - -The uri should be of the form: - - scheme://[address[:ttl=ttl][:noa=noa]]/[sessionname] - [#type=value *[&type=value]] - - where value is url encoded. This looslely resembles - http://tools.ietf.org/html/draft-fujikawa-sdp-url-01 - - - #GST_SDP_OK on success. - - - - - the start of the uri - - - - the result #GstSDPMessage - - - - - - - The contents of the SDP "o=" field which gives the originator of the session -(their username and the address of the user's host) plus a session id and -session version number. - - - the user's login on the originating host, or it is "-" - if the originating host does not support the concept of user ids. - - - - is a numeric string such that the tuple of @username, @sess_id, - @nettype, @addrtype and @addr form a globally unique identifier for the - session. - - - - a version number for this announcement - - - - the type of network. "IN" is defined to have the meaning - "Internet". - - - - the type of @addr. - - - - the globally unique address of the machine from which the session was - created. - - - - - Return values for the SDP functions. - - - A successful return value - - - a function was given invalid parameters - - - - The contents of the SDP "t=" field which specify the start and stop times for -a conference session. - - - start time for the conference. The value is the decimal - representation of Network Time Protocol (NTP) time values in seconds - - - - stop time for the conference. The value is the decimal - representation of Network Time Protocol (NTP) time values in seconds - - - - repeat times for a session - - - - - - Reset the time information in @t. - - - a #GstSDPResult. - - - - - a #GstSDPTime - - - - - - Set time information @start, @stop and @repeat in @t. - - - a #GstSDPResult. - - - - - a #GstSDPTime - - - - the start time - - - - the stop time - - - - the repeat times - - - - - - - - - The contents of the SDP "z=" field which allows the sender to -specify a list of time zone adjustments and offsets from the base -time. - - - the NTP time that a time zone adjustment happens - - - - the offset from the time when the session was first scheduled - - - - Reset the zone information in @zone. - - - a #GstSDPResult. - - - - - a #GstSDPZone - - - - - - Set zone information in @zone. - - - a #GstSDPResult. - - - - - a #GstSDPZone - - - - the NTP time that a time zone adjustment happens - - - - the offset from the time when the session was first scheduled - - - - - - - The Application-Specific Maximum bandwidth modifier. - - - - - The Conference Total bandwidth modifier. - - - - - The extension prefix bandwidth modifier. - - - - - RTCP bandwidth allocated to data receivers (RFC 3556). - - - - - RTCP bandwidth allocated to active data senders (RFC 3556). - - - - - Transport Independent Application Specific Maximum bandwidth (RFC 3890). - - - - - - - - - - - - - - - - - - - Check if the given @addr is a multicast address. - - - TRUE when @addr is multicast. - - - - - a network type - - - - an address type - - - - an address - - - - - - Makes key management data - - - a #gchar key-mgmt data, - - - - - a #gchar URI - - - - a #gchar base64-encoded key data - - - - - - Allocate a new GstSDPMedia and store the result in @media. - - - a #GstSDPResult. - - - - - pointer to new #GstSDPMedia - - - - - - Mapping of caps to SDP fields: - -a=rtpmap:(payload) (encoding_name) or (clock_rate)[or (encoding_params)] - -a=framesize:(payload) (width)-(height) - -a=fmtp:(payload) (param)[=(value)];... - -a=rtcp-fb:(payload) (param1) [param2]... - -a=extmap:(id)[/direction] (extensionname) (extensionattributes) - - - a #GstSDPResult. - - - - - a #GstCaps - - - - a #GstSDPMedia - - - - - - Creates a uri from @msg with the given @scheme. The uri has the format: - - \@scheme:///[#type=value *[&type=value]] - - Where each value is url encoded. - - - a uri for @msg. - - - - - the uri scheme - - - - the #GstSDPMessage - - - - - - Allocate a new GstSDPMessage and store the result in @msg. - - - a #GstSDPResult. - - - - - pointer to new #GstSDPMessage - - - - - - Parse @text and create a new SDPMessage from these. - - - a #GstSDPResult. - - - - - A dynamically allocated string representing the SDP description - - - - pointer to new #GstSDPMessage - - - - - - Parse the contents of @size bytes pointed to by @data and store the result in -@msg. - - - #GST_SDP_OK on success. - - - - - the start of the buffer - - - - - - the size of the buffer - - - - the result #GstSDPMessage - - - - - - Parse the null-terminated @uri and store the result in @msg. - -The uri should be of the form: - - scheme://[address[:ttl=ttl][:noa=noa]]/[sessionname] - [#type=value *[&type=value]] - - where value is url encoded. This looslely resembles - http://tools.ietf.org/html/draft-fujikawa-sdp-url-01 - - - #GST_SDP_OK on success. - - - - - the start of the uri - - - - the result #GstSDPMessage - - - - - - diff --git a/gir-files/GstTag-1.0.gir b/gir-files/GstTag-1.0.gir deleted file mode 100644 index 78b19ce91..000000000 --- a/gir-files/GstTag-1.0.gir +++ /dev/null @@ -1,1765 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - AcoustID Fingerprint (Chromaprint) - - - - - AcoustID Identifier - - - - - Direction of contrast processing applied when capturing an image. (string) - -The allowed values are: - "normal" - "soft" - "hard" - - - - - Digital zoom ratio used when capturing an image. (double) - - - - - Exposure compensation using when capturing an image in EV. (double) - - - - - Exposure mode used when capturing an image. (string) - -The allowed values are: - "auto-exposure" - "manual-exposure" - "auto-bracket" - - - - - Type of exposure control used when capturing an image. (string) - -The allowed values are: - "undefined" - "manual" - "normal" - automatically controlled - "aperture-priority" - user selects aperture value - "shutter-priority" - user selects shutter speed - "creative" - biased towards depth of field - "action" - biased towards fast shutter speed - "portrait" - closeup, leaving background out of focus - "landscape" - landscape photos, background in focus - - - - - If flash was fired during the capture of an image. (boolean) - -Note that if this tag isn't present, it should not be assumed that -the flash did not fire. It should be treated as unknown. - - - - - The flash mode selected during the capture of an image. (string) - -The allowed values are: - "auto" - "always" - "never" - - - - - Focal length used when capturing an image, in mm. (double) - - - - - 35 mm equivalent focal length used when capturing an image, in mm. (double) - - - - - Focal ratio (f-number) used when capturing an image. (double) - -The value stored is the denominator of the focal ratio (f-number). -For example, if this tag value is 2, the focal ratio is f/2. - - - - - Gain adjustment applied to an image. (string) - -The allowed values are: - "none" - "low-gain-up" - "high-gain-up" - "low-gain-down" - "high-gain-down" - - - - - ISO speed used when capturing an image. (integer) - - - - - Defines the way a camera determines the exposure. (string) - -The allowed values are: - "unknown" - "average" - "center-weighted-average" - "spot" - "multi-spot" - "pattern" - "partial" - "other" - - - - - Direction of saturation processing applied when capturing an image. (string) - -The allowed values are: - "normal" - "low-saturation" - "high-saturation" - - - - - Scene mode used when capturing an image. (string) - -The allowed values are: - "standard" - "landscape" - "portrait" - "night-scene" - - - - - Direction of sharpness processing applied when capturing an image. (string) - -The allowed values are: - "normal" - "soft" - "hard" - - - - - Shutter speed used when capturing an image, in seconds. (fraction) - - - - - Indicates the source of capture. The device/medium used to do the -capture. (string) - -Allowed values are: - "dsc" (= digital still camera) - "transparent-scanner" - "reflex-scanner" - "other" - - - - - White balance mode used when capturing an image. (string) - -The allowed values are: - "auto" - "manual" - "daylight" - "cloudy" - "tungsten" - "fluorescent" - "fluorescent h" (newer daylight-calibrated fluorescents) - "flash" - - - - - CDDB disc id in its short form (e.g. 'aa063d0f') - - - - - CDDB disc id including all details - - - - - Musicbrainz disc id (e.g. 'ahg7JUcfR3vCYBphSDIogOOWrr0-') - - - - - Musicbrainz disc id details - - - - - Annodex CMML clip element tag - - - - - Annodex CMML head element tag - - - - - Annodex CMML stream element tag - - - - - - - - - - - - - - - - - - - ID3V2 header size considered minimum input for some functions such as -gst_tag_list_from_id3v2_tag() and gst_tag_get_id3v2_tag_size() for example. - - - - - Media (image/video) intended horizontal pixel density in ppi. (double) - - - - - Media (image/video) intended vertical pixel density in ppi. (double) - - - - - Musical key in which the sound starts. It is represented as a string -with a maximum length of three characters. The ground keys are -represented with "A","B","C","D","E", "F" and "G" and halfkeys -represented with "b" and "#". Minor is represented as "m" (e.g. "Dbm"). -Off key is represented with an "o" only. -This notation might be extended in the future to support non-minor/major -keys. - - - - - MusicBrainz album artist ID - - - - - MusicBrainz album ID - - - - - MusicBrainz artist ID - - - - - MusicBrainz Release Group ID - - - - - MusicBrainz Release Track ID - - - - - MusicBrainz track ID - - - - - MusicBrainz track TRM ID - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Provides a base class for demuxing tags at the beginning or end of a -stream and handles things like typefinding, querying, seeking, and -different modes of operation (chain-based, pull_range-based, and providing -downstream elements with random access if upstream supports that). The tag -is stripped from the output, and all offsets are adjusted for the tag -sizes, so that to the downstream element the stream will appear as if -there was no tag at all. Also, once the tag has been parsed, GstTagDemux -will try to determine the media type of the resulting stream and add a -source pad with the appropriate caps in order to facilitate auto-plugging. - -## Deriving from GstTagDemux - -Subclasses have to do four things: - - * In their base init function, they must add a pad template for the sink - pad to the element class, describing the media type they can parse in - the caps of the pad template. - * In their class init function, they must override - GST_TAG_DEMUX_CLASS(demux_klass)->identify_tag with their own identify - function. - * In their class init function, they must override - GST_TAG_DEMUX_CLASS(demux_klass)->parse_tag with their own parse - function. - * In their class init function, they must also set - GST_TAG_DEMUX_CLASS(demux_klass)->min_start_size and/or - GST_TAG_DEMUX_CLASS(demux_klass)->min_end_size to the minimum size required - for the identify function to decide whether the stream has a supported tag - or not. A class parsing ID3v1 tags, for example, would set min_end_size to - 128 bytes. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - parent element - - - - - - - - - - - - - The #GstTagDemuxClass structure. See documentation at beginning of section -for details about what subclasses need to override and do. - - - the parent class. - - - - minimum size required to identify a tag at the start and -determine its total size. Set to 0 if not interested in start tags. -Subclasses should set this in their class_init function. - - - - minimum size required to identify a tag at the end and -determine its total size. Set to 0 if not interested in end tags. -Subclasses should set this in their class_init function. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Result values from the parse_tag virtual function. - - cannot parse tag, just skip it - - - call again with less or more data - - - parsed tag successfully - - - - Type of image contained in an image tag (specified as "image-type" field in -the info structure in the image's #GstSample) - - No image type. Can be used to - tell functions such as gst_tag_image_data_to_image_sample() that no - image type should be set. - - - Undefined/other image type - - - Cover (front) - - - Cover (back) - - - Leaflet page - - - Medium (e.g. label side of CD) - - - Lead artist/lead performer/soloist - - - Artist/performer - - - Conductor - - - Band/orchestra - - - Composer - - - Lyricist/text writer - - - Recording location - - - During recording - - - During performance - - - Movie/video screen capture - - - A fish as funny as the ID3v2 spec - - - Illustration - - - Band/artist logotype - - - Publisher/studio logotype - - - - See http://creativecommons.org/ns for more information. - - making multiple copies - is allowed - - - distribution, public display - and public performance are allowed - - - distribution of derivative - works is allowed - - - commercial derivatives are allowed, - but only non-commercial distribution is allowed - - - copyright and license notices - must be kept intact - - - credit must be given to - copyright holder and/or author - - - derivative works must be - licensed under the same terms or compatible terms as the original work - - - source code (the preferred - form for making modifications) must be provided when exercising some - rights granted by the license - - - derivative and combined works - must be licensed under specified terms, similar to those of the original - work - - - derivative works must be - licensed under specified terms, with at least the same conditions as - the original work; combinations with the work may be licensed under - different terms - - - exercising rights for - commercial purposes is prohibited - - - use in a - non-developing country is prohibited - - - this license was created - by the Creative Commons project - - - this license was - created by the Free Software Foundation (FSF) - - - - Provides a base class for adding tags at the beginning or end of a -stream. - -## Deriving from GstTagMux - -Subclasses have to do the following things: - - * In their base init function, they must add pad templates for the sink - pad and the source pad to the element class, describing the media type - they accept and output in the caps of the pad template. - * In their class init function, they must override the - GST_TAG_MUX_CLASS(mux_klass)->render_start_tag and/or - GST_TAG_MUX_CLASS(mux_klass)->render_end_tag vfuncs and set up a render - function. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - parent element - - - - - - - - - - - - - The #GstTagMuxClass structure. Subclasses need to override at least one -of the two render vfuncs. - - - the parent class. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This interface is implemented by elements that are able to do XMP serialization. Examples for -such elements are #jifmux and #qtmux. - -Applications can use this interface to configure which XMP schemas should be used when serializing -tags into XMP. Schemas are represented by their names, a full list of the supported schemas can be -obtained from gst_tag_xmp_list_schemas(). By default, all schemas are used. - - - - Adds all available XMP schemas to the configuration. Meaning that -all will be used. - - - - - - - a #GstTagXmpWriter - - - - - - Adds @schema to the list schemas - - - - - - - a #GstTagXmpWriter - - - - the schema to be added - - - - - - Checks if @schema is going to be used - - - %TRUE if it is going to be used - - - - - a #GstTagXmpWriter - - - - the schema to test - - - - - - Removes all schemas from the list of schemas to use. Meaning that no -XMP will be generated. - - - - - - - a #GstTagXmpWriter - - - - - - Removes a schema from the list of schemas to use. Nothing is done if -the schema wasn't in the list - - - - - - - a #GstTagXmpWriter - - - - the schema to remove - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Check if a given string contains a known ISO 639 language code. - -This is useful in situations where it's not clear whether a given -string is a language code (which should be put into a #GST_TAG_LANGUAGE_CODE -tag) or a free-form language name descriptor (which should be put into a -#GST_TAG_LANGUAGE_NAME tag instead). - - - TRUE if the two- or three-letter language code in @lang_code - is a valid ISO-639 language code. - - - - - ISO-639 language code (e.g. "deu" or "ger" or "de") - - - - - - Convenience function to read a string with unknown character encoding. If -the string is already in UTF-8 encoding, it will be returned right away. -If not it tries to detect byte-order-mark for UTF-16/32 cases and use that. -Otherwise, the environment will be searched for a number of environment -variables (whose names are specified in the NULL-terminated string array -@env_vars) containing a list of character encodings to try/use. If none -are specified, the current locale will be tried. If that also doesn't work, -WINDOWS-1252/ISO-8859-1 is assumed (which will almost always succeed). - - - a newly-allocated string in UTF-8 encoding, or NULL - - - - - string data - - - - - - length of string data, or -1 if the string is NUL-terminated - - - - - a NULL-terminated string array of environment variable names, or NULL - - - - - - - - Looks up the GStreamer tag for a ID3v2 tag. - - - The corresponding GStreamer tag or NULL if none exists. - - - - - ID3v2 tag to convert to GStreamer tag - - - - - - Looks up the GStreamer tag for an ID3v2 user tag (e.g. description in -TXXX frame or owner in UFID frame). - - - The corresponding GStreamer tag or NULL if none exists. - - - - - the type of ID3v2 user tag (e.g. "TXXX" or "UDIF") - - - - ID3v2 user tag to convert to GStreamer tag - - - - - - Looks up the GStreamer tag for a vorbiscomment tag. - - - The corresponding GStreamer tag or NULL if none exists. - - - - - vorbiscomment tag to convert to GStreamer tag - - - - - - Determines size of an ID3v2 tag on buffer containing at least ID3v2 header, -i.e. at least #GST_TAG_ID3V2_HEADER_SIZE (10) bytes; - - - Size of tag, or 0 if header is invalid or too small. - - - - - buffer holding ID3v2 tag (or at least the start of one) - - - - - - Convenience macro wrapping gst_tag_get_language_code_iso_639_1(). - - - - ISO-639 language code (e.g. "deu" or "ger" or "de") - - - - - Returns two-letter ISO-639-1 language code given a three-letter ISO-639-2 -language code or two-letter ISO-639-1 language code (both are accepted for -convenience). - -Language codes are case-sensitive and expected to be lower case. - - - two-letter ISO-639-1 language code string that maps to @lang_code, - or NULL if no mapping is known. The returned string must not be - modified or freed. - - - - - ISO-639 language code (e.g. "deu" or "ger" or "de") - - - - - - Returns three-letter ISO-639-2 "bibliographic" language code given a -two-letter ISO-639-1 language code or a three-letter ISO-639-2 language -code (both are accepted for convenience). - -The "bibliographic" code is derived from the English name of the language -(e.g. "ger" for German instead of "de" or "deu"). In most scenarios, the -"terminological" codes are preferred. - -Language codes are case-sensitive and expected to be lower case. - - - three-letter ISO-639-2 language code string that maps to @lang_code, - or NULL if no mapping is known. The returned string must not be - modified or freed. - - - - - ISO-639 language code (e.g. "deu" or "ger" or "de") - - - - - - Returns three-letter ISO-639-2 "terminological" language code given a -two-letter ISO-639-1 language code or a three-letter ISO-639-2 language -code (both are accepted for convenience). - -The "terminological" code is derived from the local name of the language -(e.g. "deu" for German instead of "ger"). In most scenarios, the -"terminological" codes are preferred over the "bibliographic" ones. - -Language codes are case-sensitive and expected to be lower case. - - - three-letter ISO-639-2 language code string that maps to @lang_code, - or NULL if no mapping is known. The returned string must not be - modified or freed. - - - - - ISO-639 language code (e.g. "deu" or "ger" or "de") - - - - - - Returns a list of known language codes (in form of two-letter ISO-639-1 -codes). This is useful for UIs to build a list of available languages for -tagging purposes (e.g. to tag an audio track appropriately in a video or -audio editor). - - - NULL-terminated string array with two-letter - language codes. Free with g_strfreev() when no longer needed. - - - - - - - Returns the name of the language given an ISO-639 language code as -found in a GST_TAG_LANGUAGE_CODE tag. The name will be translated -according to the current locale (if the library was built against the -iso-codes package, otherwise the English name will be returned). - -Language codes are case-sensitive and expected to be lower case. - - - language name in UTF-8 format, or NULL if @language_code could - not be mapped to a language name. The returned string must not be - modified and does not need to freed; it will stay valid until the - application is terminated. - - - - - two or three-letter ISO-639 language code - - - - - - Get the description of a license, which is a translated description -of the license's main features. - - - the description of the license, or NULL if the license is unknown - or a description is not available. - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Get the flags of a license, which describe most of the features of -a license in their most general form. - - - the flags of the license, or 0 if the license is unknown - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Get the jurisdiction code of a license. This is usually a two-letter -ISO 3166-1 alpha-2 code, but there is also the special case of Scotland, -for which no code exists and which is thus represented as "scotland". - -Known jurisdictions: ar, at, au, be, bg, br, ca, ch, cl, cn, co, de, -dk, es, fi, fr, hr, hu, il, in, it, jp, kr, mk, mt, mx, my, nl, pe, pl, -pt, scotland, se, si, tw, uk, us, za. - - - the jurisdiction code of the license, or NULL if the license is - unknown or is not specific to a particular jurisdiction. - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Get the nick name of a license, which is a short (untranslated) string -such as e.g. "CC BY-NC-ND 2.0 UK". - - - the nick name of the license, or NULL if the license is unknown - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Get the title of a license, which is a short translated description -of the license's features (generally not very pretty though). - - - the title of the license, or NULL if the license is unknown or - no title is available. - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Get the version of a license. - - - the version of the license, or NULL if the license is not known or - has no version - - - - - a license reference string in form of a URI, - e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/" - - - - - - Returns a list of known license references (in form of URIs). This is -useful for UIs to build a list of available licenses for tagging purposes -(e.g. to tag an audio track appropriately in a video or audio editor, or -an image in a camera application). - - - NULL-terminated array of license strings. Free - with g_strfreev() when no longer needed. - - - - - - - Gets the number of ID3v1 genres that can be identified. Winamp genres are -included. - - - the number of ID3v1 genres that can be identified - - - - - Gets the ID3v1 genre name for a given ID. - - - the genre or NULL if no genre is associated with that ID. - - - - - ID of genre to query - - - - - - Helper function for tag-reading plugins to create a #GstSample suitable to -add to a #GstTagList as an image tag (such as #GST_TAG_IMAGE or -#GST_TAG_PREVIEW_IMAGE) from the encoded image data and an (optional) image -type. - -Background: cover art and other images in tags are usually stored as a -blob of binary image data, often accompanied by a MIME type or some other -content type string (e.g. 'png', 'jpeg', 'jpg'). Sometimes there is also an -'image type' to indicate what kind of image this is (e.g. front cover, -back cover, artist, etc.). The image data may also be an URI to the image -rather than the image itself. - -In GStreamer, image tags are #GstSample<!-- -->s containing the raw image -data, with the sample caps describing the content type of the image -(e.g. image/jpeg, image/png, text/uri-list). The sample info may contain -an additional 'image-type' field of #GstTagImageType to describe -the type of image (front cover, back cover etc.). #GST_TAG_PREVIEW_IMAGE -tags should not carry an image type, their type is already indicated via -the special tag name. - -This function will do various checks and typefind the encoded image -data (we can't trust the declared mime type). - - - a newly-allocated image sample for use in tag lists, or NULL - - - - - the (encoded) image - - - - - - the length of the encoded image data at @image_data - - - - type of the image, or #GST_TAG_IMAGE_TYPE_UNDEFINED. Pass - #GST_TAG_IMAGE_TYPE_NONE if no image type should be set at all (e.g. - for preview images) - - - - - - Adds an image from an ID3 APIC frame (or similar, such as used in FLAC) -to the given tag list. Also see gst_tag_image_data_to_image_sample() for -more information on image tags in GStreamer. - - - %TRUE if the image was processed, otherwise %FALSE - - - - - a tag list - - - - the (encoded) image - - - - - - the length of the encoded image data at @image_data - - - - picture type as per the ID3 (v2.4.0) specification for - the APIC frame (0 = unknown/other) - - - - - - Parses the IFD and IFD tags data contained in the buffer and puts it -on a taglist. The base_offset is used to subtract from the offset in -the tag entries and be able to get the offset relative to the buffer -start - - - The parsed taglist - - - - - The exif buffer - - - - byte order of the data - - - - Offset from the tiff header to this buffer - - - - - - Parses the exif tags starting with a tiff header structure. - - - The taglist - - - - - The exif buffer - - - - - - Creates a new tag list that contains the information parsed out of a -ID3 tag. - - - A new #GstTagList with all tags that could be extracted from the - given vorbiscomment buffer or NULL on error. - - - - - buffer to convert - - - - - - Creates a new tag list that contains the information parsed out of a -vorbiscomment packet. - - - A new #GstTagList with all tags that could be extracted from the - given vorbiscomment buffer or NULL on error. - - - - - data to convert - - - - - - size of @data - - - - identification data at start of stream - - - - - - length of identification data - - - - pointer to a string that should take the - vendor string of this vorbis comment or NULL if you don't need it. - - - - - - Creates a new tag list that contains the information parsed out of a -vorbiscomment packet. - - - A new #GstTagList with all tags that could be extracted from the - given vorbiscomment buffer or NULL on error. - - - - - buffer to convert - - - - identification data at start of stream - - - - - - length of identification data - - - - pointer to a string that should take the - vendor string of this vorbis comment or NULL if you don't need it. - - - - - - Parse a xmp packet into a taglist. - - - new taglist or %NULL, free the list when done - - - - - buffer - - - - - - Parses the data containing an ID3v1 tag and returns a #GstTagList from the -parsed data. - - - A new tag list or NULL if the data was not an ID3v1 tag. - - - - - 128 bytes of data containing the ID3v1 tag - - - - - - - - Formats the tags in taglist on exif format. The resulting buffer contains -the tags IFD and is followed by the data pointed by the tag entries. - - - A GstBuffer containing the tag entries followed by the tag data - - - - - The taglist - - - - byte order used in writing (G_LITTLE_ENDIAN or G_BIG_ENDIAN) - - - - Offset from the tiff header first byte - - - - - - Formats the tags in taglist into exif structure, a tiff header -is put in the beginning of the buffer. - - - A GstBuffer containing the data - - - - - The taglist - - - - - - Creates a new vorbiscomment buffer from a tag list. - - - A new #GstBuffer containing a vorbiscomment buffer with all tags - that could be converted from the given tag list. - - - - - tag list to convert - - - - identification data at start of stream - - - - - - length of identification data, may be 0 if @id_data is NULL - - - - string that describes the vendor string or NULL - - - - - - Formats a taglist as a xmp packet using only the selected -schemas. An empty list (%NULL) means that all schemas should -be used - - - new buffer or %NULL, unref the buffer when done - - - - - tags - - - - does the container forbid inplace editing - - - - - %NULL terminated array of schemas to be used on serialization - - - - - - - - Convenience function to parse a GST_TAG_EXTENDED_COMMENT string and -separate it into its components. - -If successful, @key, @lang and/or @value will be set to newly allocated -strings that you need to free with g_free() when done. @key and @lang -may also be set to NULL by this function if there is no key or no language -code in the extended comment string. - - - TRUE if the string could be parsed, otherwise FALSE - - - - - an extended comment string, see #GST_TAG_EXTENDED_COMMENT - - - - - return location for the comment description key, or NULL - - - - - return location for the comment ISO-639 language code, or NULL - - - - return location for the actual comment string, or NULL - - - - whether to fail if strings are not in key=value form - - - - - - Registers additional musicbrainz-specific tags with the GStreamer tag -system. Plugins and applications that use these tags should call this -function before using them. Can be called multiple times. - - - - - - - Looks up the ID3v2 tag for a GStreamer tag. - - - The corresponding ID3v2 tag or NULL if none exists. - - - - - GStreamer tag to convert to vorbiscomment tag - - - - - - Creates a new tag list that contains the information parsed out of a -vorbiscomment packet. - - - A #GList of newly-allocated - key=value strings. Free with g_list_foreach (list, (GFunc) g_free, NULL) - plus g_list_free (list) - - - - - - - a #GstTagList - - - - a GStreamer tag identifier, such as #GST_TAG_ARTIST - - - - - - Looks up the vorbiscomment tag for a GStreamer tag. - - - The corresponding vorbiscomment tag or NULL if none exists. - - - - - GStreamer tag to convert to vorbiscomment tag - - - - - - Gets the list of supported schemas in the xmp lib - - - a %NULL terminated array of strings with the - schema names - - - - - - - Convenience function using gst_tag_from_vorbis_tag(), parsing -a vorbis comment string into the right type and adding it to the -given taglist @list. - -Unknown vorbiscomment tags will be added to the tag list in form -of a #GST_TAG_EXTENDED_COMMENT. - - - - - - - a #GstTagList - - - - a vorbiscomment tag string (key in key=value), must be valid UTF-8 - - - - a vorbiscomment value string (value in key=value), must be valid UTF-8 - - - - - - diff --git a/gir-files/GstVideo-1.0.gir b/gir-files/GstVideo-1.0.gir deleted file mode 100644 index e7372a439..000000000 --- a/gir-files/GstVideo-1.0.gir +++ /dev/null @@ -1,16492 +0,0 @@ - - - - - - - - - - - - - - A bufferpool option to enable extra padding. When a bufferpool supports this -option, gst_buffer_pool_config_set_video_alignment() can be called. - -When this option is enabled on the bufferpool, -#GST_BUFFER_POOL_OPTION_VIDEO_META should also be enabled. - - - - - An option that can be activated on a bufferpool to request gl texture upload -meta on buffers from the pool. - -When this option is enabled on the bufferpool, -@GST_BUFFER_POOL_OPTION_VIDEO_META should also be enabled. - - - - - An option that can be activated on bufferpool to request video metadata -on buffers from the pool. - - - - - Name of the caps feature indicating that the stream is interlaced. - -Currently it is only used for video with 'interlace-mode=alternate' -to ensure backwards compatibility for this new mode. -In this mode each buffer carries a single field of interlaced video. -@GST_VIDEO_BUFFER_FLAG_TOP_FIELD and @GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD -indicate whether the buffer carries a top or bottom field. The order of -buffers/fields in the stream and the timestamps on the buffers indicate the -temporal order of the fields. -Top and bottom fields are expected to alternate in this mode. -The frame rate in the caps still signals the frame rate, so the notional field -rate will be twice the frame rate from the caps -(see @GST_VIDEO_INFO_FIELD_RATE_N). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This interface is implemented by elements which can perform some color -balance operation on video frames they process. For example, modifying -the brightness, contrast, hue or saturation. - -Example elements are 'xvimagesink' and 'colorbalance' - - - Get the #GstColorBalanceType of this implementation. - - - A the #GstColorBalanceType. - - - - - The #GstColorBalance implementation - - - - - - Retrieve the current value of the indicated channel, between min_value -and max_value. - -See Also: The #GstColorBalanceChannel.min_value and - #GstColorBalanceChannel.max_value members of the - #GstColorBalanceChannel object. - - - The current value of the channel. - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - - - Retrieve a list of the available channels. - - - A - GList containing pointers to #GstColorBalanceChannel - objects. The list is owned by the #GstColorBalance - instance and must not be freed. - - - - - - - A #GstColorBalance instance - - - - - - Sets the current value of the channel to the passed value, which must -be between min_value and max_value. - -See Also: The #GstColorBalanceChannel.min_value and - #GstColorBalanceChannel.max_value members of the - #GstColorBalanceChannel object. - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - The new value for the channel. - - - - - - A helper function called by implementations of the GstColorBalance -interface. It fires the #GstColorBalance::value-changed signal on the -instance, and the #GstColorBalanceChannel::value-changed signal on the -channel object. - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel whose value has changed - - - - The new value of the channel - - - - - - Get the #GstColorBalanceType of this implementation. - - - A the #GstColorBalanceType. - - - - - The #GstColorBalance implementation - - - - - - Retrieve the current value of the indicated channel, between min_value -and max_value. - -See Also: The #GstColorBalanceChannel.min_value and - #GstColorBalanceChannel.max_value members of the - #GstColorBalanceChannel object. - - - The current value of the channel. - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - - - Retrieve a list of the available channels. - - - A - GList containing pointers to #GstColorBalanceChannel - objects. The list is owned by the #GstColorBalance - instance and must not be freed. - - - - - - - A #GstColorBalance instance - - - - - - Sets the current value of the channel to the passed value, which must -be between min_value and max_value. - -See Also: The #GstColorBalanceChannel.min_value and - #GstColorBalanceChannel.max_value members of the - #GstColorBalanceChannel object. - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - The new value for the channel. - - - - - - A helper function called by implementations of the GstColorBalance -interface. It fires the #GstColorBalance::value-changed signal on the -instance, and the #GstColorBalanceChannel::value-changed signal on the -channel object. - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel whose value has changed - - - - The new value of the channel - - - - - - Fired when the value of the indicated channel has changed. - - - - - - The #GstColorBalanceChannel - - - - The new value - - - - - - - The #GstColorBalanceChannel object represents a parameter -for modifying the color balance implemented by an element providing the -#GstColorBalance interface. For example, Hue or Saturation. - - - - - - - - - - - - - - - - - - - - A string containing a descriptive name for this channel - - - - The minimum valid value for this channel. - - - - The maximum valid value for this channel. - - - - - - - - - Fired when the value of the indicated channel has changed. - - - - - - The new value - - - - - - - Color-balance channel class. - - - the parent class - - - - - - - - - - - - - - - - - - - - - - - - - - Color-balance interface. - - - the parent interface - - - - - - - A - GList containing pointers to #GstColorBalanceChannel - objects. The list is owned by the #GstColorBalance - instance and must not be freed. - - - - - - - A #GstColorBalance instance - - - - - - - - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - The new value for the channel. - - - - - - - - - - The current value of the channel. - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel instance - - - - - - - - - - A the #GstColorBalanceType. - - - - - The #GstColorBalance implementation - - - - - - - - - - - - - - A #GstColorBalance instance - - - - A #GstColorBalanceChannel whose value has changed - - - - The new value of the channel - - - - - - - - - - - - - An enumeration indicating whether an element implements color balancing -operations in software or in dedicated hardware. In general, dedicated -hardware implementations (such as those provided by xvimagesink) are -preferred. - - Color balance is implemented with dedicated - hardware. - - - Color balance is implemented via software - processing. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This metadata stays relevant as long as video colorspace is unchanged. - - - - - This metadata stays relevant as long as video orientation is unchanged. - - - - - This metadata stays relevant as long as video size is unchanged. - - - - - This metadata is relevant for video streams. - - - - - - - - - - - - - - - - - - - The Navigation interface is used for creating and injecting navigation related -events such as mouse button presses, cursor motion and key presses. The associated -library also provides methods for parsing received events, and for sending and -receiving navigation related bus events. One main usecase is DVD menu navigation. - -The main parts of the API are: - -* The GstNavigation interface, implemented by elements which provide an application - with the ability to create and inject navigation events into the pipeline. -* GstNavigation event handling API. GstNavigation events are created in response to - calls on a GstNavigation interface implementation, and sent in the pipeline. Upstream - elements can use the navigation event API functions to parse the contents of received - messages. - -* GstNavigation message handling API. GstNavigation messages may be sent on the message - bus to inform applications of navigation related changes in the pipeline, such as the - mouse moving over a clickable region, or the set of available angles changing. - -The GstNavigation message functions provide functions for creating and parsing -custom bus messages for signaling GstNavigation changes. - - - Inspect a #GstEvent and return the #GstNavigationEventType of the event, or -#GST_NAVIGATION_EVENT_INVALID if the event is not a #GstNavigation event. - - - - - - - A #GstEvent to inspect. - - - - - - Inspect a #GstNavigation command event and retrieve the enum value of the -associated command. - - - TRUE if the navigation command could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to GstNavigationCommand to receive the - type of the navigation event. - - - - - - - - - - - - A #GstEvent to inspect. - - - - A pointer to a location to receive - the string identifying the key press. The returned string is owned by the - event, and valid only until the event is unreffed. - - - - - - Retrieve the details of either a #GstNavigation mouse button press event or -a mouse button release event. Determine which type the event is using -gst_navigation_event_get_type() to retrieve the #GstNavigationEventType. - - - TRUE if the button number and both coordinates could be extracted, - otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gint that will receive the button - number associated with the event. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse button event. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse button event. - - - - - - Inspect a #GstNavigation mouse movement event and extract the coordinates -of the event. - - - TRUE if both coordinates could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse movement. - - - - - - Inspect a #GstNavigation mouse scroll event and extract the coordinates -of the event. - - - TRUE if all coordinates could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the delta_x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the delta_y coordinate of the - mouse movement. - - - - - - Check a bus message to see if it is a #GstNavigation event, and return -the #GstNavigationMessageType identifying the type of the message if so. - - - The type of the #GstMessage, or -#GST_NAVIGATION_MESSAGE_INVALID if the message is not a #GstNavigation -notification. - - - - - A #GstMessage to inspect. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_ANGLES_CHANGED for notifying an application -that the current angle, or current number of angles available in a -multiangle video has changed. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - The currently selected angle. - - - - The number of viewing angles now available. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_EVENT. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - A navigation #GstEvent - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_MOUSE_OVER. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - %TRUE if the mouse has entered a clickable area of the display. -%FALSE if it over a non-clickable area. - - - - - - Parse a #GstNavigation message of type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED -and extract the @cur_angle and @n_angles parameters. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - A pointer to a #guint to receive the new - current angle number, or NULL - - - - A pointer to a #guint to receive the new angle - count, or NULL. - - - - - - Parse a #GstNavigation message of type #GST_NAVIGATION_MESSAGE_EVENT -and extract contained #GstEvent. The caller must unref the @event when done -with it. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - a pointer to a #GstEvent to receive - the contained navigation event. - - - - - - Parse a #GstNavigation message of type #GST_NAVIGATION_MESSAGE_MOUSE_OVER -and extract the active/inactive flag. If the mouse over event is marked -active, it indicates that the mouse is over a clickable area. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - A pointer to a gboolean to receive the - active/inactive state, or NULL. - - - - - - Inspect a #GstQuery and return the #GstNavigationQueryType associated with -it if it is a #GstNavigation query. - - - The #GstNavigationQueryType of the query, or -#GST_NAVIGATION_QUERY_INVALID - - - - - The query to inspect - - - - - - Create a new #GstNavigation angles query. When executed, it will -query the pipeline for the set of currently available angles, which may be -greater than one in a multiangle video. - - - The new query. - - - - - Create a new #GstNavigation commands query. When executed, it will -query the pipeline for the set of currently available commands. - - - The new query. - - - - - Parse the current angle number in the #GstNavigation angles @query into the -#guint pointed to by the @cur_angle variable, and the number of available -angles into the #guint pointed to by the @n_angles variable. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - Pointer to a #guint into which to store the - currently selected angle value from the query, or NULL - - - - Pointer to a #guint into which to store the - number of angles value from the query, or NULL - - - - - - Parse the number of commands in the #GstNavigation commands @query. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - the number of commands in this query. - - - - - - Parse the #GstNavigation command query and retrieve the @nth command from -it into @cmd. If the list contains less elements than @nth, @cmd will be -set to #GST_NAVIGATION_COMMAND_INVALID. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - the nth command to retrieve. - - - - a pointer to store the nth command into. - - - - - - Set the #GstNavigation angles query result field in @query. - - - - - - - a #GstQuery - - - - the current viewing angle to set. - - - - the number of viewing angles to set. - - - - - - Set the #GstNavigation command query result fields in @query. The number -of commands passed must be equal to @n_commands. - - - - - - - a #GstQuery - - - - the number of commands to set. - - - - A list of @GstNavigationCommand values, @n_cmds entries long. - - - - - - Set the #GstNavigation command query result fields in @query. The number -of commands passed must be equal to @n_commands. - - - - - - - a #GstQuery - - - - the number of commands to set. - - - - An array containing @n_cmds - @GstNavigationCommand values. - - - - - - - - - - - - - - - - - - - - - - Sends the indicated command to the navigation interface. - - - - - - - The navigation interface instance - - - - The command to issue - - - - - - - - - - - - - - - - - - - - - - - - - - The navigation interface instance - - - - The type of the key event. Recognised values are "key-press" and -"key-release" - - - - Character representation of the key. This is typically as produced -by XKeysymToString. - - - - - - Sends a mouse event to the navigation interface. Mouse event coordinates -are sent relative to the display space of the related output area. This is -usually the size in pixels of the window associated with the element -implementing the #GstNavigation interface. - - - - - - - The navigation interface instance - - - - The type of mouse event, as a text string. Recognised values are -"mouse-button-press", "mouse-button-release" and "mouse-move". - - - - The button number of the button being pressed or released. Pass 0 -for mouse-move events. - - - - The x coordinate of the mouse event. - - - - The y coordinate of the mouse event. - - - - - - Sends a mouse scroll event to the navigation interface. Mouse event coordinates -are sent relative to the display space of the related output area. This is -usually the size in pixels of the window associated with the element -implementing the #GstNavigation interface. - - - - - - - The navigation interface instance - - - - The x coordinate of the mouse event. - - - - The y coordinate of the mouse event. - - - - The delta_x coordinate of the mouse event. - - - - The delta_y coordinate of the mouse event. - - - - - - - A set of commands that may be issued to an element providing the -#GstNavigation interface. The available commands can be queried via -the gst_navigation_query_new_commands() query. - -For convenience in handling DVD navigation, the MENU commands are aliased as: - GST_NAVIGATION_COMMAND_DVD_MENU = @GST_NAVIGATION_COMMAND_MENU1 - GST_NAVIGATION_COMMAND_DVD_TITLE_MENU = @GST_NAVIGATION_COMMAND_MENU2 - GST_NAVIGATION_COMMAND_DVD_ROOT_MENU = @GST_NAVIGATION_COMMAND_MENU3 - GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU = @GST_NAVIGATION_COMMAND_MENU4 - GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU = @GST_NAVIGATION_COMMAND_MENU5 - GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU = @GST_NAVIGATION_COMMAND_MENU6 - GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU = @GST_NAVIGATION_COMMAND_MENU7 - - An invalid command entry - - - Execute navigation menu command 1. For DVD, -this enters the DVD root menu, or exits back to the title from the menu. - - - Execute navigation menu command 2. For DVD, -this jumps to the DVD title menu. - - - Execute navigation menu command 3. For DVD, -this jumps into the DVD root menu. - - - Execute navigation menu command 4. For DVD, -this jumps to the Subpicture menu. - - - Execute navigation menu command 5. For DVD, -the jumps to the audio menu. - - - Execute navigation menu command 6. For DVD, -this jumps to the angles menu. - - - Execute navigation menu command 7. For DVD, -this jumps to the chapter menu. - - - Select the next button to the left in a menu, -if such a button exists. - - - Select the next button to the right in a menu, -if such a button exists. - - - Select the button above the current one in a -menu, if such a button exists. - - - Select the button below the current one in a -menu, if such a button exists. - - - Activate (click) the currently selected -button in a menu, if such a button exists. - - - Switch to the previous angle in a -multiangle feature. - - - Switch to the next angle in a multiangle -feature. - - - - Enum values for the various events that an element implementing the -GstNavigation interface might send up the pipeline. - - Returned from -gst_navigation_event_get_type() when the passed event is not a navigation event. - - - A key press event. Use -gst_navigation_event_parse_key_event() to extract the details from the event. - - - A key release event. Use -gst_navigation_event_parse_key_event() to extract the details from the event. - - - A mouse button press event. Use -gst_navigation_event_parse_mouse_button_event() to extract the details from the -event. - - - A mouse button release event. Use -gst_navigation_event_parse_mouse_button_event() to extract the details from the -event. - - - A mouse movement event. Use -gst_navigation_event_parse_mouse_move_event() to extract the details from the -event. - - - A navigation command event. Use -gst_navigation_event_parse_command() to extract the details from the event. - - - A mouse scroll event. Use -gst_navigation_event_parse_mouse_scroll_event() to extract the details from -the event. (Since: 1.18) - - - - Navigation interface. - - - the parent interface - - - - - - - - - - - - - - - - - - - - - A set of notifications that may be received on the bus when navigation -related status changes. - - Returned from -gst_navigation_message_get_type() when the passed message is not a -navigation message. - - - Sent when the mouse moves over or leaves a -clickable region of the output, such as a DVD menu button. - - - Sent when the set of available commands -changes and should re-queried by interested applications. - - - Sent when display angles in a multi-angle -feature (such as a multiangle DVD) change - either angles have appeared or -disappeared. - - - Sent when a navigation event was not handled -by any element in the pipeline (Since: 1.6) - - - - Types of navigation interface queries. - - invalid query - - - command query - - - viewing angle query - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Returns the #GstVideoAncillaryDID16 of the ancillary data. - - - - a #GstVideoAncillary - - - - - Check if GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD is set on @buf (Since: 1.18). - - - - a #GstBuffer - - - - - Check if GST_VIDEO_BUFFER_FLAG_TOP_FIELD is set on @buf (Since: 1.18). - - - - a #GstBuffer - - - - - - - - - - - - - - - - - - - Generic caps string for video, for use in pad templates. - - - - string format that describes the pixel layout, as string - (e.g. "I420", "RGB", "YV12", "YUY2", "AYUV", etc.) - - - - - Generic caps string for video, for use in pad templates. - - - - Requires caps features as a string, e.g. - "memory:SystemMemory". - - - string format that describes the pixel layout, as string - (e.g. "I420", "RGB", "YV12", "YUY2", "AYUV", etc.) - - - - - The entire set of flags for the @frame - - - - a #GstVideoCodecFrame - - - - - Checks whether the given @flag is set - - - - a #GstVideoCodecFrame - - - a flag to check for - - - - - This macro sets the given bits - - - - a #GstVideoCodecFrame - - - Flag to set, can be any number of bits in guint32. - - - - - This macro usets the given bits. - - - - a #GstVideoCodecFrame - - - Flag to unset - - - - - Tests if the buffer should only be decoded but not sent downstream. - - - - a #GstVideoCodecFrame - - - - - Tests if the frame must be encoded as a keyframe. Applies only to -frames provided to encoders. Decoders can safely ignore this field. - - - - a #GstVideoCodecFrame - - - - - Tests if encoder should output stream headers before outputting the -resulting encoded buffer for the given frame. - -Applies only to frames provided to encoders. Decoders can safely -ignore this field. - - - - a #GstVideoCodecFrame - - - - - Tests if the frame is a synchronization point (like a keyframe). - -Decoder implementations can use this to detect keyframes. - - - - a #GstVideoCodecFrame - - - - - Sets the buffer to not be sent downstream. - -Decoder implementation can use this if they have frames that -are not meant to be displayed. - -Encoder implementation can safely ignore this field. - - - - a #GstVideoCodecFrame - - - - - - - - - - - - - - - - - - - Sets the frame to be a synchronization point (like a keyframe). - -Encoder implementations should set this accordingly. - -Decoder implementing parsing features should set this when they -detect such a synchronization point. - - - - a #GstVideoCodecFrame - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #GstVideoAlphaMode, the alpha mode to use. -Default is #GST_VIDEO_ALPHA_MODE_COPY. - - - - - #G_TYPE_DOUBLE, the alpha color value to use. -Default to 1.0 - - - - - #G_TYPE_UINT, the border color to use if #GST_VIDEO_CONVERTER_OPT_FILL_BORDER -is set to %TRUE. The color is in ARGB format. -Default 0xff000000 - - - - - #GstVideoChromaMode, set the chroma resample mode subsampled -formats. Default is #GST_VIDEO_CHROMA_MODE_FULL. - - - - - #GstVideoChromaMethod, The resampler method to use for -chroma resampling. Other options for the resampler can be used, see -the #GstVideoResampler. Default is #GST_VIDEO_RESAMPLER_METHOD_LINEAR - - - - - #G_TYPE_INT, height in the destination frame, default destination height - - - - - #G_TYPE_INT, width in the destination frame, default destination width - - - - - #G_TYPE_INT, x position in the destination frame, default 0 - - - - - #G_TYPE_INT, y position in the destination frame, default 0 - - - - - #GstVideoDitherMethod, The dither method to use when -changing bit depth. -Default is #GST_VIDEO_DITHER_BAYER. - - - - - #G_TYPE_UINT, The quantization amount to dither to. Components will be -quantized to multiples of this value. -Default is 1 - - - - - #G_TYPE_BOOLEAN, if the destination rectangle does not fill the complete -destination image, render a border with -#GST_VIDEO_CONVERTER_OPT_BORDER_ARGB. Otherwise the unusded pixels in the -destination are untouched. Default %TRUE. - - - - - #GstVideoGammaMode, set the gamma mode. -Default is #GST_VIDEO_GAMMA_MODE_NONE. - - - - - #GstVideoMatrixMode, set the color matrix conversion mode for -converting between Y'PbPr and non-linear RGB (R'G'B'). -Default is #GST_VIDEO_MATRIX_MODE_FULL. - - - - - #GstVideoPrimariesMode, set the primaries conversion mode. -Default is #GST_VIDEO_PRIMARIES_MODE_NONE. - - - - - #GstVideoResamplerMethod, The resampler method to use for -resampling. Other options for the resampler can be used, see -the #GstVideoResampler. Default is #GST_VIDEO_RESAMPLER_METHOD_CUBIC - - - - - #G_TYPE_UINT, The number of taps for the resampler. -Default is 0: let the resampler choose a good value. - - - - - #G_TYPE_INT, source height to convert, default source height - - - - - #G_TYPE_INT, source width to convert, default source width - - - - - #G_TYPE_INT, source x position to start conversion, default 0 - - - - - #G_TYPE_INT, source y position to start conversion, default 0 - - - - - #G_TYPE_UINT, maximum number of threads to use. Default 1, 0 for the number -of cores. - - - - - - - - - - - - - - - - - - - - - - - - - - Utility function that video decoder elements can use in case they encountered -a data processing error that may be fatal for the current "data unit" but -need not prevent subsequent decoding. Such errors are counted and if there -are too many, as configured in the context's max_errors, the pipeline will -post an error message and the application will be requested to stop further -media processing. Otherwise, it is considered a "glitch" and only a warning -is logged. In either case, @ret is set to the proper value to -return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK). - - - - the base video decoder element that generates the error - - - element defined weight of the error, added to error count - - - like CORE, LIBRARY, RESOURCE or STREAM (see #gstreamer-GstGError) - - - error code defined for that domain (see #gstreamer-GstGError) - - - the message to display (format string and args enclosed in - parentheses) - - - debugging information for the message (format string and args - enclosed in parentheses) - - - variable to receive return value - - - - - - - - - - - - Gives the segment of the element. - - - - base decoder instance - - - - - Default maximum number of errors tolerated before signaling error. - - - - - Gives the segment of the element. - - - - base decoder instance - - - - - The name of the templates for the sink pad. - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - a #GstVideoDecoder - - - - - The name of the templates for the source pad. - - - - - Gives the pointer to the source #GstPad object of the element. - - - - a #GstVideoDecoder - - - - - Obtain a lock to protect the decoder function from concurrent access. - - - - video decoder instance - - - - - Release the lock that protects the decoder function from concurrent access. - - - - video decoder instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gives the segment of the element. - - - - base parse instance - - - - - Gives the segment of the element. - - - - base parse instance - - - - - The name of the templates for the sink pad. - - - - - Gives the pointer to the sink #GstPad object of the element. - - - - a #GstVideoEncoder - - - - - The name of the templates for the source pad. - - - - - Gives the pointer to the source #GstPad object of the element. - - - - a #GstVideoEncoder - - - - - Obtain a lock to protect the encoder function from concurrent access. - - - - video encoder instance - - - - - Release the lock that protects the encoder function from concurrent access. - - - - video encoder instance - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - List of all video formats, for use in template caps strings. - -Formats are sorted by decreasing "quality", using these criteria by priority: - - number of components - - depth - - subsampling factor of the width - - subsampling factor of the height - - number of planes - - native endianness preferred - - pixel stride - - poffset - - prefer non-complex formats - - prefer YUV formats over RGB ones - - prefer I420 over YV12 - - format name - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Number of planes. This is the number of planes the pixel layout is -organized in in memory. The number of planes can be less than the -number of components (e.g. Y,U,V,A or R, G, B, A) when multiple -components are packed into one plane. - -Examples: RGB/RGBx/RGBA: 1 plane, 3/3/4 components; -I420: 3 planes, 3 components; NV21/NV12: 2 planes, 3 components. - - - - a #GstVideoFormatInfo - - - - - - - - - - - - - - - - Plane number where the given component can be found. A plane may -contain data for multiple components. - - - - a #GstVideoFormatInfo - - - the component index - - - - - - - - - - - - - - pixel stride for the given component. This is the amount of bytes to the -pixel immediately to the right, so basically bytes from one pixel to the -next. When bits < 8, the stride is expressed in bits. - -Examples: for 24-bit RGB, the pixel stride would be 3 bytes, while it -would be 4 bytes for RGBx or ARGB, and 8 bytes for ARGB64 or AYUV64. -For planar formats such as I420 the pixel stride is usually 1. For -YUY2 it would be 2 bytes. - - - - a #GstVideoFormatInfo - - - the component index - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Row stride in bytes, that is number of bytes from the first pixel component -of a row to the first pixel component in the next row. This might include -some row padding (memory not actually used for anything, to make sure the -beginning of the next row is aligned in a particular way). - - - - a #GstVideoFormatInfo - - - an array of strides - - - the component index - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The height of a field. It's the height of the full frame unless split-field -(alternate) interlacing is in use. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The padded height in pixels of a plane (padded size divided by the plane stride). -In case of GST_VIDEO_INTERLACE_MODE_ALTERNATE info, this macro returns the -plane heights used to hold a single field, not the full frame. - -The size passed as third argument is the size of the pixel data and should -not contain any extra metadata padding. - -It is not valid to use this macro with a TILED format. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - G_TYPE_DOUBLE, B parameter of the cubic filter. The B -parameter controls the bluriness. Values between 0.0 and -2.0 are accepted. 1/3 is the default. - -Below are some values of popular filters: - B C -Hermite 0.0 0.0 -Spline 1.0 0.0 -Catmull-Rom 0.0 1/2 -Mitchell 1/3 1/3 -Robidoux 0.3782 0.3109 -Robidoux - Sharp 0.2620 0.3690 -Robidoux - Soft 0.6796 0.1602 - - - - - G_TYPE_DOUBLE, C parameter of the cubic filter. The C -parameter controls the Keys alpha value. Values between 0.0 and -2.0 are accepted. 1/3 is the default. - -See #GST_VIDEO_RESAMPLER_OPT_CUBIC_B for some more common values - - - - - G_TYPE_DOUBLE, specifies the size of filter envelope for -@GST_VIDEO_RESAMPLER_METHOD_LANCZOS. values are clamped between -1.0 and 5.0. 2.0 is the default. - - - - - G_TYPE_INT, limits the maximum number of taps to use. -16 is the default. - - - - - G_TYPE_DOUBLE, specifies sharpening of the filter for -@GST_VIDEO_RESAMPLER_METHOD_LANCZOS. values are clamped between -0.0 and 1.0. 0.0 is the default. - - - - - G_TYPE_DOUBLE, specifies sharpness of the filter for -@GST_VIDEO_RESAMPLER_METHOD_LANCZOS. values are clamped between -0.5 and 1.5. 1.0 is the default. - - - - - #GstVideoDitherMethod, The dither method to use for propagating -quatization errors. - - - - - - - - - - - - Cast @obj to a #GstVideoSink without runtime type check. - - - - a #GstVideoSink or derived object - - - - - - - - - - - - - - - - - - - - - - - - - - Get the sink #GstPad of @obj. - - - - a #GstVideoSink - - - - - - - - - - - - - - - - - - - - - - - - - use this macro to create new tile modes. - - - - the mode number to create - - - the tile mode type - - - - - Encode the number of tile in X and Y into the stride. - - - - number of tiles in X - - - number of tiles in Y - - - - - Check if @mode is an indexed tile type - - - - a tile mode - - - - - Get the tile mode type of @mode - - - - the tile mode - - - - - - - - - - - - - Extract the number of tiles in X from the stride value. - - - - plane stride - - - - - - - - - Extract the number of tiles in Y from the stride value. - - - - plane stride - - - - - - - - - Active Format Description (AFD) - -For details, see Table 6.14 Active Format in: - -ATSC Digital Television Standard: -Part 4 – MPEG-2 Video System Characteristics - -https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf - -and Active Format Description in Complete list of AFD codes - -https://en.wikipedia.org/wiki/Active_Format_Description#Complete_list_of_AFD_codes - -and SMPTE ST2016-1 - - - parent #GstMeta - - - - 0 for progressive or field 1 and 1 for field 2 - - - - #GstVideoAFDSpec that applies to @afd - - - - #GstVideoAFDValue AFD value - - - - - - - - - - - Enumeration of the different standards that may apply to AFD data: - -0) ETSI/DVB: -https://www.etsi.org/deliver/etsi_ts/101100_101199/101154/02.01.01_60/ts_101154v020101p.pdf - -1) ATSC A/53: -https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf - -2) SMPTE ST2016-1: - - AFD value is from DVB/ETSI standard - - - AFD value is from ATSC A/53 standard - - - - - - Enumeration of the various values for Active Format Description (AFD) - -AFD should be included in video user data whenever the rectangular -picture area containing useful information does not extend to the full height or width of the coded -frame. AFD data may also be included in user data when the rectangular picture area containing -useful information extends to the full height and width of the coded frame. - -For details, see Table 6.14 Active Format in: - -ATSC Digital Television Standard: -Part 4 – MPEG-2 Video System Characteristics - -https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf - -and Active Format Description in Complete list of AFD codes - -https://en.wikipedia.org/wiki/Active_Format_Description#Complete_list_of_AFD_codes - -and SMPTE ST2016-1 - -Notes: - -1) AFD 0 is undefined for ATSC and SMPTE ST2016-1, indicating that AFD data is not available: -If Bar Data is not present, AFD '0000' indicates that exact information -is not available and the active image should be assumed to be the same as the coded frame. AFD '0000'. -AFD '0000' accompanied by Bar Data signals that the active image’s aspect ratio is narrower than 16:9, -but is not 4:3 or 14:9. As the exact aspect ratio cannot be conveyed by AFD alone, wherever possible, -AFD ‘0000’ should be accompanied by Bar Data to define the exact vertical or horizontal extent -of the active image. -2) AFD 0 is reserved for DVB/ETSI -3) values 1, 5, 6, 7, and 12 are reserved for both ATSC and DVB/ETSI -4) values 2 and 3 are not recommended for ATSC, but are valid for DVB/ETSI - - Unavailable (see note 0 below). - - - For 4:3 coded frame, letterbox 16:9 image, - at top of the coded frame. For 16:9 coded frame, full frame 16:9 image, - the same as the coded frame. - - - For 4:3 coded frame, letterbox 14:9 image, - at top of the coded frame. For 16:9 coded frame, pillarbox 14:9 image, - horizontally centered in the coded frame. - - - For 4:3 coded frame, letterbox image with an aspect ratio - greater than 16:9, vertically centered in the coded frame. For 16:9 coded frame, - letterbox image with an aspect ratio greater than 16:9. - - - For 4:3 coded frame, full frame 4:3 image, - the same as the coded frame. For 16:9 coded frame, full frame 16:9 image, the same as - the coded frame. - - - For 4:3 coded frame, full frame 4:3 image, the same as - the coded frame. For 16:9 coded frame, pillarbox 4:3 image, horizontally centered in the - coded frame. - - - For 4:3 coded frame, letterbox 16:9 image, vertically centered in - the coded frame with all image areas protected. For 16:9 coded frame, full frame 16:9 image, - with all image areas protected. - - - For 4:3 coded frame, letterbox 14:9 image, vertically centered in - the coded frame. For 16:9 coded frame, pillarbox 14:9 image, horizontally centered in the - coded frame. - - - For 4:3 coded frame, full frame 4:3 image, with alternative 14:9 - center. For 16:9 coded frame, pillarbox 4:3 image, with alternative 14:9 center. - - - For 4:3 coded frame, letterbox 16:9 image, with alternative 14:9 - center. For 16:9 coded frame, full frame 16:9 image, with alternative 14:9 center. - - - For 4:3 coded frame, letterbox 16:9 image, with alternative 4:3 - center. For 16:9 coded frame, full frame 16:9 image, with alternative 4:3 center. - - - - - - - - - - - - - - - - - - Extra buffer metadata for performing an affine transformation using a 4x4 -matrix. The transformation matrix can be composed with -gst_video_affine_transformation_meta_apply_matrix(). - -The vertices operated on are all in the range 0 to 1, not in -Normalized Device Coordinates (-1 to +1). Transforming points in this space -are assumed to have an origin at (0.5, 0.5, 0.5) in a left-handed coordinate -system with the x-axis moving horizontally (positive values to the right), -the y-axis moving vertically (positive values up the screen) and the z-axis -perpendicular to the screen (positive values into the screen). - - - parent #GstMeta - - - - the column-major 4x4 transformation matrix - - - - - - Apply a transformation using the given 4x4 transformation matrix. -Performs the multiplication, meta->matrix X matrix. - - - - - - - a #GstVideoAffineTransformationMeta - - - - a 4x4 transformation matrix to be applied - - - - - - - - - - - - - - - VideoAggregator can accept AYUV, ARGB and BGRA video streams. For each of the requested -sink pads it will compare the incoming geometry and framerate to define the -output parameters. Indeed output video frames will have the geometry of the -biggest incoming video stream and the framerate of the fastest incoming one. - -VideoAggregator will do colorspace conversion. - -Zorder for each input stream can be configured on the -#GstVideoAggregatorPad. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #GstVideoInfo representing the currently set -srcpad caps. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - An implementation of GstPad that can be used with #GstVideoAggregator. - -See #GstVideoAggregator for more details. - - - - - - - - - - - - - - - - - - - - Requests the pad to check and update the converter before the next usage to -update for any changes that have happened. - - - - - - - a #GstVideoAggregatorPad - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Returns the currently queued buffer that is going to be used -for the current output frame. - -This must only be called from the #GstVideoAggregatorClass::aggregate_frames virtual method, -or from the #GstVideoAggregatorPadClass::prepare_frame virtual method of the aggregator pads. - -The return value is only valid until #GstVideoAggregatorClass::aggregate_frames or #GstVideoAggregatorPadClass::prepare_frame -returns. - - - The currently queued buffer - - - - - a #GstVideoAggregatorPad - - - - - - Returns the currently prepared video frame that has to be aggregated into -the current output frame. - -This must only be called from the #GstVideoAggregatorClass::aggregate_frames virtual method, -or from the #GstVideoAggregatorPadClass::prepare_frame virtual method of the aggregator pads. - -The return value is only valid until #GstVideoAggregatorClass::aggregate_frames or #GstVideoAggregatorPadClass::prepare_frame -returns. - - - The currently prepared video frame - - - - - a #GstVideoAggregatorPad - - - - - - Checks if the pad currently has a buffer queued that is going to be used -for the current output frame. - -This must only be called from the #GstVideoAggregatorClass::aggregate_frames virtual method, -or from the #GstVideoAggregatorPadClass::prepare_frame virtual method of the aggregator pads. - - - %TRUE if the pad has currently a buffer queued - - - - - a #GstVideoAggregatorPad - - - - - - Allows selecting that this pad requires an output format with alpha - - - - - - - a #GstVideoAggregatorPad - - - - %TRUE if this pad requires alpha output - - - - - - - - - - - - - - - - - - The #GstVideoInfo currently set on the pad - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extra alignment parameters for the memory of video buffers. This -structure is usually used to configure the bufferpool if it supports the -#GST_BUFFER_POOL_OPTION_VIDEO_ALIGNMENT. - - - extra pixels on the top - - - - extra pixels on the bottom - - - - extra pixels on the left side - - - - extra pixels on the right side - - - - array with extra alignment requirements for the strides - - - - - - Set @align to its default values with no padding and no alignment. - - - - - - - a #GstVideoAlignment - - - - - - - Different alpha modes. - - When input and output have alpha, it will be copied. - When the input has no alpha, alpha will be set to - #GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE - - - set all alpha to - #GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE - - - multiply all alpha with - #GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE. - When the input format has no alpha but the output format has, the - alpha value will be set to #GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE - - - - Video Ancillary data, according to SMPTE-291M specification. - -Note that the contents of the data are always stored as 8bit data (i.e. do not contain -the parity check bits). - - - The Data Identifier - - - - The Secondary Data Identifier (if type 2) or the Data - Block Number (if type 1) - - - - The amount of data (in bytes) in @data (max 255 bytes) - - - - The user data content of the Ancillary packet. - Does not contain the ADF, DID, SDID nor CS. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Some know types of Ancillary Data identifiers. - - CEA 708 Ancillary data according to SMPTE 334 - - - CEA 608 Ancillary data according to SMPTE 334 - - - AFD/Bar Ancillary data according to SMPTE 2016-3 (Since: 1.18) - - - - Bar data should be included in video user data -whenever the rectangular picture area containing useful information -does not extend to the full height or width of the coded frame -and AFD alone is insufficient to describe the extent of the image. - -Note: either vertical or horizontal bars are specified, but not both. - -For more details, see: - -https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf - -and SMPTE ST2016-1 - - - parent #GstMeta - - - - 0 for progressive or field 1 and 1 for field 2 - - - - if true then bar data specifies letterbox, otherwise pillarbox - - - - If @is_letterbox is true, then the value specifies the - last line of a horizontal letterbox bar area at top of reconstructed frame. - Otherwise, it specifies the last horizontal luminance sample of a vertical pillarbox - bar area at the left side of the reconstructed frame - - - - If @is_letterbox is true, then the value specifies the - first line of a horizontal letterbox bar area at bottom of reconstructed frame. - Otherwise, it specifies the first horizontal - luminance sample of a vertical pillarbox bar area at the right side of the reconstructed frame. - - - - - - - - - - - Additional video buffer flags. These flags can potentially be used on any -buffers carrying closed caption data, or video data - even encoded data. - -Note that these are only valid for #GstCaps of type: video/... and caption/... -They can conflict with other extended buffer flags. - - If the #GstBuffer is interlaced. In mixed - interlace-mode, this flags specifies if the frame is - interlaced or progressive. - - - If the #GstBuffer is interlaced, then the first field - in the video frame is the top field. If unset, the - bottom field is first. - - - If the #GstBuffer is interlaced, then the first field - (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF flag setting) - is repeated. - - - If the #GstBuffer is interlaced, then only the - first field (as defined by the %GST_VIDEO_BUFFER_FLAG_TFF - flag setting) is to be displayed (Since: 1.16). - - - The #GstBuffer contains one or more specific views, - such as left or right eye view. This flags is set on - any buffer that contains non-mono content - even for - streams that contain only a single viewpoint. In mixed - mono / non-mono streams, the absence of the flag marks - mono buffers. - - - When conveying stereo/multiview content with - frame-by-frame methods, this flag marks the first buffer - in a bundle of frames that belong together. - - - The video frame has the top field only. This is the - same as GST_VIDEO_BUFFER_FLAG_TFF | - GST_VIDEO_BUFFER_FLAG_ONEFIELD (Since: 1.16). - Use GST_VIDEO_BUFFER_IS_TOP_FIELD() to check for this flag. - - - The video frame has the bottom field only. This is - the same as GST_VIDEO_BUFFER_FLAG_ONEFIELD - (GST_VIDEO_BUFFER_FLAG_TFF flag unset) (Since: 1.16). - Use GST_VIDEO_BUFFER_IS_BOTTOM_FIELD() to check for this flag. - - - The #GstBuffer contains the end of a video field or frame - boundary such as the last subframe or packet (Since: 1.18). - - - Offset to define more flags - - - - - - Create a new bufferpool that can allocate video frames. This bufferpool -supports all the video bufferpool options. - - - a new #GstBufferPool to allocate video frames - - - - - - - - - - - - - - - - - - - - - Extra buffer metadata providing Closed Caption. - - - parent #GstMeta - - - - The type of Closed Caption contained in the meta. - - - - The Closed Caption data. - - - - - - The size in bytes of @data - - - - - - - - - - - The various known types of Closed Caption (CC). - - Unknown type of CC - - - CEA-608 as byte pairs. Note that - this format is not recommended since is does not specify to - which field the caption comes from and therefore assumes - it comes from the first field (and that there is no information - on the second field). Use @GST_VIDEO_CAPTION_TYPE_CEA708_RAW - if you wish to store CEA-608 from two fields and prefix each byte pair - with 0xFC for the first field and 0xFD for the second field. - - - CEA-608 as byte triplets as defined - in SMPTE S334-1 Annex A. The second and third byte of the byte triplet - is the raw CEA608 data, the first byte is a bitfield: The top/7th bit is - 0 for the second field, 1 for the first field, bit 6 and 5 are 0 and - bits 4 to 0 are a 5 bit unsigned integer that represents the line - offset relative to the base-line of the original image format (line 9 - for 525-line field 1, line 272 for 525-line field 2, line 5 for - 625-line field 1 and line 318 for 625-line field 2). - - - CEA-708 as cc_data byte triplets. They - can also contain 608-in-708 and the first byte of each triplet has to - be inspected for detecting the type. - - - CEA-708 (and optionally CEA-608) in - a CDP (Caption Distribution Packet) defined by SMPTE S-334-2. - Contains the whole CDP (starting with 0x9669). - - - Parses fixed Closed Caption #GstCaps and returns the corresponding caption -type, or %GST_VIDEO_CAPTION_TYPE_UNKNOWN. - - - #GstVideoCaptionType. - - - - - Fixed #GstCaps to parse - - - - - - Creates new caps corresponding to @type. - - - new #GstCaps - - - - - #GstVideoCaptionType - - - - - - - Extra flags that influence the result from gst_video_chroma_resample_new(). - - no flags - - - the input is interlaced - - - - Different subsampling and upsampling methods - - Duplicates the chroma samples when - upsampling and drops when subsampling - - - Uses linear interpolation to reconstruct - missing chroma and averaging to subsample - - - - Different chroma downsampling and upsampling modes - - do full chroma up and down sampling - - - only perform chroma upsampling - - - only perform chroma downsampling - - - disable chroma resampling - - - - - - Perform resampling of @width chroma pixels in @lines. - - - - - - - a #GstVideoChromaResample - - - - pixel lines - - - - the number of pixels on one line - - - - - - Free @resample - - - - - - - a #GstVideoChromaResample - - - - - - The resampler must be fed @n_lines at a time. The first line should be -at @offset. - - - - - - - a #GstVideoChromaResample - - - - the number of input lines - - - - the first line - - - - - - Create a new resampler object for the given parameters. When @h_factor or -@v_factor is > 0, upsampling will be used, otherwise subsampling is -performed. - - - a new #GstVideoChromaResample that should be freed with - gst_video_chroma_resample_free() after usage. - - - - - a #GstVideoChromaMethod - - - - a #GstVideoChromaSite - - - - #GstVideoChromaFlags - - - - the #GstVideoFormat - - - - horizontal resampling factor - - - - vertical resampling factor - - - - - - - Various Chroma sitings. - - unknown cositing - - - no cositing - - - chroma is horizontally cosited - - - chroma is vertically cosited - - - choma samples are sited on alternate lines - - - chroma samples cosited with luma samples - - - jpeg style cositing, also for mpeg1 and mjpeg - - - mpeg2 style cositing - - - DV style cositing - - - - A #GstVideoCodecFrame represents a video frame both in raw and -encoded form. - - - - - - - - - Unique identifier for the frame. Use this if you need - to get hold of the frame later (like when data is being decoded). - Typical usage in decoders is to set this on the opaque value provided - to the library and get back the frame using gst_video_decoder_get_frame() - - - - - - - - - - Decoding timestamp - - - - Presentation timestamp - - - - Duration of the frame - - - - Distance in frames from the last synchronization point. - - - - the input #GstBuffer that created this frame. The buffer is owned - by the frame and references to the frame instead of the buffer should - be kept. - - - - the output #GstBuffer. Implementations should set this either - directly, or by using the - @gst_video_decoder_allocate_output_frame() or - @gst_video_decoder_allocate_output_buffer() methods. The buffer is - owned by the frame and references to the frame instead of the - buffer should be kept. - - - - Running time when the frame will be used. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Gets private data set on the frame by the subclass via -gst_video_codec_frame_set_user_data() previously. - - - The previously set user_data - - - - - a #GstVideoCodecFrame - - - - - - Increases the refcount of the given frame by one. - - - @buf - - - - - a #GstVideoCodecFrame - - - - - - Sets @user_data on the frame and the #GDestroyNotify that will be called when -the frame is freed. Allows to attach private data by the subclass to frames. - -If a @user_data was previously set, then the previous set @notify will be called -before the @user_data is replaced. - - - - - - - a #GstVideoCodecFrame - - - - private data - - - - a #GDestroyNotify - - - - - - Decreases the refcount of the frame. If the refcount reaches 0, the frame -will be freed. - - - - - - - a #GstVideoCodecFrame - - - - - - - Flags for #GstVideoCodecFrame - - - is the frame only meant to be decoded - - - is the frame a synchronization point (keyframe) - - - should the output frame be made a keyframe - - - should the encoder output stream headers - - - - Structure representing the state of an incoming or outgoing video -stream for encoders and decoders. - -Decoders and encoders will receive such a state through their -respective @set_format vmethods. - -Decoders and encoders can set the downstream state, by using the -@gst_video_decoder_set_output_state() or -@gst_video_encoder_set_output_state() methods. - - - - - - The #GstVideoInfo describing the stream - - - - The #GstCaps used in the caps negotiation of the pad. - - - - a #GstBuffer corresponding to the - 'codec_data' field of a stream, or NULL. - - - - The #GstCaps for allocation query and pool - negotiation. Since: 1.10 - - - - - - - - - Increases the refcount of the given state by one. - - - @buf - - - - - a #GstVideoCodecState - - - - - - Decreases the refcount of the state. If the refcount reaches 0, the state -will be freed. - - - - - - - a #GstVideoCodecState - - - - - - - The color matrix is used to convert between Y'PbPr and -non-linear RGB (R'G'B') - - unknown matrix - - - identity matrix. Order of coefficients is -actually GBR, also IEC 61966-2-1 (sRGB) - - - FCC Title 47 Code of Federal Regulations 73.682 (a)(20) - - - ITU-R BT.709 color matrix, also ITU-R BT1361 -/ IEC 61966-2-4 xvYCC709 / SMPTE RP177 Annex B - - - ITU-R BT.601 color matrix, also SMPTE170M / ITU-R BT1358 525 / ITU-R BT1700 NTSC - - - SMPTE 240M color matrix - - - ITU-R BT.2020 color matrix. Since: 1.6 - - - Converts the @value to the #GstVideoColorMatrix -The matrix coefficients (MatrixCoefficients) value is -defined by "ISO/IEC 23001-8 Section 7.3 Table 4" -and "ITU-T H.273 Table 4". -"H.264 Table E-5" and "H.265 Table E.5" share the identical values. - - - the matched #GstVideoColorMatrix - - - - - a ITU-T H.273 matrix coefficients value - - - - - - Get the coefficients used to convert between Y'PbPr and R'G'B' using @matrix. - -When: - -|[ - 0.0 <= [Y',R',G',B'] <= 1.0) - (-0.5 <= [Pb,Pr] <= 0.5) -]| - -the general conversion is given by: - -|[ - Y' = Kr*R' + (1-Kr-Kb)*G' + Kb*B' - Pb = (B'-Y')/(2*(1-Kb)) - Pr = (R'-Y')/(2*(1-Kr)) -]| - -and the other way around: - -|[ - R' = Y' + Cr*2*(1-Kr) - G' = Y' - Cb*2*(1-Kb)*Kb/(1-Kr-Kb) - Cr*2*(1-Kr)*Kr/(1-Kr-Kb) - B' = Y' + Cb*2*(1-Kb) -]| - - - TRUE if @matrix was a YUV color format and @Kr and @Kb contain valid - values. - - - - - a #GstVideoColorMatrix - - - - result red channel coefficient - - - - result blue channel coefficient - - - - - - Converts #GstVideoColorMatrix to the "matrix coefficients" -(MatrixCoefficients) value defined by "ISO/IEC 23001-8 Section 7.3 Table 4" -and "ITU-T H.273 Table 4". -"H.264 Table E-5" and "H.265 Table E.5" share the identical values. - - - The value of ISO/IEC 23001-8 matrix coefficients. - - - - - a #GstVideoColorMatrix - - - - - - - The color primaries define the how to transform linear RGB values to and from -the CIE XYZ colorspace. - - unknown color primaries - - - BT709 primaries, also ITU-R BT1361 / IEC -61966-2-4 / SMPTE RP177 Annex B - - - BT470M primaries, also FCC Title 47 Code -of Federal Regulations 73.682 (a)(20) - - - BT470BG primaries, also ITU-R BT601-6 -625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM - - - SMPTE170M primaries, also ITU-R -BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC - - - SMPTE240M primaries - - - Generic film (colour filters using -Illuminant C) - - - ITU-R BT2020 primaries. Since: 1.6 - - - Adobe RGB primaries. Since: 1.8 - - - SMPTE ST 428 primaries (CIE 1931 -XYZ). Since: 1.16 - - - SMPTE RP 431 primaries (ST 431-2 -(2011) / DCI P3). Since: 1.16 - - - SMPTE EG 432 primaries (ST 432-1 -(2010) / P3 D65). Since: 1.16 - - - EBU 3213 primaries (JEDEC P22 -phosphors). Since: 1.16 - - - Converts the @value to the #GstVideoColorPrimaries -The colour primaries (ColourPrimaries) value is -defined by "ISO/IEC 23001-8 Section 7.1 Table 2" and "ITU-T H.273 Table 2". -"H.264 Table E-3" and "H.265 Table E.3" share the identical values. - - - the matched #GstVideoColorPrimaries - - - - - a ITU-T H.273 colour primaries value - - - - - - Get information about the chromaticity coordinates of @primaries. - - - a #GstVideoColorPrimariesInfo for @primaries. - - - - - a #GstVideoColorPrimaries - - - - - - Converts #GstVideoColorPrimaries to the "colour primaries" (ColourPrimaries) -value defined by "ISO/IEC 23001-8 Section 7.1 Table 2" -and "ITU-T H.273 Table 2". -"H.264 Table E-3" and "H.265 Table E.3" share the identical values. - - - The value of ISO/IEC 23001-8 colour primaries. - - - - - a #GstVideoColorPrimaries - - - - - - - Structure describing the chromaticity coordinates of an RGB system. These -values can be used to construct a matrix to transform RGB to and from the -XYZ colorspace. - - - a #GstVideoColorPrimaries - - - - reference white x coordinate - - - - reference white y coordinate - - - - red x coordinate - - - - red y coordinate - - - - green x coordinate - - - - green y coordinate - - - - blue x coordinate - - - - blue y coordinate - - - - - Possible color range values. These constants are defined for 8 bit color -values and can be scaled for other bit depths. - - unknown range - - - [0..255] for 8 bit components - - - [16..235] for 8 bit components. Chroma has - [16..240] range. - - - Compute the offset and scale values for each component of @info. For each -component, (c[i] - offset[i]) / scale[i] will scale the component c[i] to the -range [0.0 .. 1.0]. - -The reverse operation (c[i] * scale[i]) + offset[i] can be used to convert -the component values in range [0.0 .. 1.0] back to their representation in -@info and @range. - - - - - - - a #GstVideoColorRange - - - - a #GstVideoFormatInfo - - - - output offsets - - - - - - output scale - - - - - - - - - Structure describing the color info. - - - the color range. This is the valid range for the samples. - It is used to convert the samples to Y'PbPr values. - - - - the color matrix. Used to convert between Y'PbPr and - non-linear RGB (R'G'B') - - - - the transfer function. used to convert between R'G'B' and RGB - - - - color primaries. used to convert between R'G'B' and CIE XYZ - - - - Parse the colorimetry string and update @cinfo with the parsed -values. - - - %TRUE if @color points to valid colorimetry info. - - - - - a #GstVideoColorimetry - - - - a colorimetry string - - - - - - Compare the 2 colorimetry sets for equality - - - %TRUE if @cinfo and @other are equal. - - - - - a #GstVideoColorimetry - - - - another #GstVideoColorimetry - - - - - - Check if the colorimetry information in @info matches that of the -string @color. - - - %TRUE if @color conveys the same colorimetry info as the color -information in @info. - - - - - a #GstVideoInfo - - - - a colorimetry string - - - - - - Make a string representation of @cinfo. - - - a string representation of @cinfo -or %NULL if all the entries of @cinfo are unknown values. - - - - - a #GstVideoColorimetry - - - - - - - Content light level information specified in CEA-861.3, Appendix A. - - - the maximum content light level - (abbreviated to MaxCLL) in candelas per square meter (cd/m^2 and nit) - - - - the maximum frame average light level - (abbreviated to MaxFLL) in candelas per square meter (cd/m^2 and nit) - - - - - - - - - Parse @caps and update @linfo - - - %TRUE if @linfo was successfully set to @caps - - - - - a #GstVideoContentLightLevel - - - - a #GstCaps - - - - - - Parse @caps and update @linfo - - - if @caps has #GstVideoContentLightLevel and could be parsed - - - - - a #GstVideoContentLightLevel - - - - a #GstCaps - - - - - - Parse the value of content-light-level caps field and update @minfo -with the parsed values. - - - %TRUE if @linfo points to valid #GstVideoContentLightLevel. - - - - - a #GstVideoContentLightLevel - - - - a content-light-level string from caps - - - - - - Initialize @linfo - - - - - - - a #GstVideoContentLightLevel - - - - - - Convert @linfo to its string representation. - - - a string representation of @linfo. - - - - - a #GstVideoContentLightLevel - - - - - - - - - - - - - - - - - - - - - - - - - - Convert the pixels of @src into @dest using @convert. - - - - - - - a #GstVideoConverter - - - - a #GstVideoFrame - - - - a #GstVideoFrame - - - - - - Free @convert - - - - - - - a #GstVideoConverter - - - - - - Get the current configuration of @convert. - - - a #GstStructure that remains valid for as long as @convert is valid - or until gst_video_converter_set_config() is called. - - - - - a #GstVideoConverter - - - - - - Set @config as extra configuration for @convert. - -If the parameters in @config can not be set exactly, this function returns -%FALSE and will try to update as much state as possible. The new state can -then be retrieved and refined with gst_video_converter_get_config(). - -Look at the `GST_VIDEO_CONVERTER_OPT_*` fields to check valid configuration -option and values. - - - %TRUE when @config could be set. - - - - - a #GstVideoConverter - - - - a #GstStructure - - - - - - Create a new converter object to convert between @in_info and @out_info -with @config. - - - a #GstVideoConverter or %NULL if conversion is not possible. - - - - - a #GstVideoInfo - - - - a #GstVideoInfo - - - - a #GstStructure with configuration options - - - - - - - Extra buffer metadata describing image cropping. - - - parent #GstMeta - - - - the horizontal offset - - - - the vertical offset - - - - the cropped width - - - - the cropped height - - - - - - - - - - - This base class is for video decoders turning encoded data into raw video -frames. - -The GstVideoDecoder base class and derived subclasses should cooperate as -follows: - -## Configuration - - * Initially, GstVideoDecoder calls @start when the decoder element - is activated, which allows the subclass to perform any global setup. - - * GstVideoDecoder calls @set_format to inform the subclass of caps - describing input video data that it is about to receive, including - possibly configuration data. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - - * Incoming data buffers are processed as needed, described in Data - Processing below. - - * GstVideoDecoder calls @stop at end of all processing. - -## Data processing - - * The base class gathers input data, and optionally allows subclass - to parse this into subsequently manageable chunks, typically - corresponding to and referred to as 'frames'. - - * Each input frame is provided in turn to the subclass' @handle_frame - callback. - The ownership of the frame is given to the @handle_frame callback. - - * If codec processing results in decoded data, the subclass should call - @gst_video_decoder_finish_frame to have decoded data pushed. - downstream. Otherwise, the subclass must call - @gst_video_decoder_drop_frame, to allow the base class to do timestamp - and offset tracking, and possibly to requeue the frame for a later - attempt in the case of reverse playback. - -## Shutdown phase - - * The GstVideoDecoder class calls @stop to inform the subclass that data - parsing will be stopped. - -## Additional Notes - - * Seeking/Flushing - - * When the pipeline is seeked or otherwise flushed, the subclass is - informed via a call to its @reset callback, with the hard parameter - set to true. This indicates the subclass should drop any internal data - queues and timestamps and prepare for a fresh set of buffers to arrive - for parsing and decoding. - - * End Of Stream - - * At end-of-stream, the subclass @parse function may be called some final - times with the at_eos parameter set to true, indicating that the element - should not expect any more data to be arriving, and it should parse and - remaining frames and call gst_video_decoder_have_frame() if possible. - -The subclass is responsible for providing pad template caps for -source and sink pads. The pads need to be named "sink" and "src". It also -needs to provide information about the output caps, when they are known. -This may be when the base class calls the subclass' @set_format function, -though it might be during decoding, before calling -@gst_video_decoder_finish_frame. This is done via -@gst_video_decoder_set_output_state - -The subclass is also responsible for providing (presentation) timestamps -(likely based on corresponding input ones). If that is not applicable -or possible, the base class provides limited framerate based interpolation. - -Similarly, the base class provides some limited (legacy) seeking support -if specifically requested by the subclass, as full-fledged support -should rather be left to upstream demuxer, parser or alike. This simple -approach caters for seeking and duration reporting using estimated input -bitrates. To enable it, a subclass should call -@gst_video_decoder_set_estimate_rate to enable handling of incoming -byte-streams. - -The base class provides some support for reverse playback, in particular -in case incoming data is not packetized or upstream does not provide -fragments on keyframe boundaries. However, the subclass should then be -prepared for the parsing and frame processing stage to occur separately -(in normal forward processing, the latter immediately follows the former), -The subclass also needs to ensure the parsing stage properly marks -keyframes, unless it knows the upstream elements will do so properly for -incoming data. - -The bare minimum that a functional subclass needs to implement is: - - * Provide pad templates - * Inform the base class of output caps via - @gst_video_decoder_set_output_state - - * Parse input data, if it is not considered packetized from upstream - Data will be provided to @parse which should invoke - @gst_video_decoder_add_to_frame and @gst_video_decoder_have_frame to - separate the data belonging to each video frame. - - * Accept data in @handle_frame and provide decoded results to - @gst_video_decoder_finish_frame, or call @gst_video_decoder_drop_frame. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiate with downstream elements to currently configured #GstVideoCodecState. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoDecoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Removes next @n_bytes of input data and adds it to currently parsed frame. - - - - - - - a #GstVideoDecoder - - - - the number of bytes to add - - - - - - Helper function that allocates a buffer to hold a video frame for @decoder's -current #GstVideoCodecState. - -You should use gst_video_decoder_allocate_output_frame() instead of this -function, if possible at all. - - - allocated buffer, or NULL if no buffer could be - allocated (e.g. when downstream is flushing or shutting down) - - - - - a #GstVideoDecoder - - - - - - Helper function that allocates a buffer to hold a video frame for @decoder's -current #GstVideoCodecState. Subclass should already have configured video -state and set src pad caps. - -The buffer allocated here is owned by the frame and you should only -keep references to the frame, not the buffer. - - - %GST_FLOW_OK if an output buffer could be allocated - - - - - a #GstVideoDecoder - - - - a #GstVideoCodecFrame - - - - - - Same as #gst_video_decoder_allocate_output_frame except it allows passing -#GstBufferPoolAcquireParams to the sub call gst_buffer_pool_acquire_buffer. - - - %GST_FLOW_OK if an output buffer could be allocated - - - - - a #GstVideoDecoder - - - - a #GstVideoCodecFrame - - - - a #GstBufferPoolAcquireParams - - - - - - Similar to gst_video_decoder_finish_frame(), but drops @frame in any -case and posts a QoS message with the frame's details on the bus. -In any case, the frame is considered finished and released. - - - a #GstFlowReturn, usually GST_FLOW_OK. - - - - - a #GstVideoDecoder - - - - the #GstVideoCodecFrame to drop - - - - - - @frame should have a valid decoded data buffer, whose metadata fields -are then appropriately set according to frame data and pushed downstream. -If no output data is provided, @frame is considered skipped. -In any case, the frame is considered finished and released. - -After calling this function the output buffer of the frame is to be -considered read-only. This function will also change the metadata -of the buffer. - - - a #GstFlowReturn resulting from sending data downstream - - - - - a #GstVideoDecoder - - - - a decoded #GstVideoCodecFrame - - - - - - Lets #GstVideoDecoder sub-classes to know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after use it. - - - - - - - a #GstVideoDecoder - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - - - the instance of the #GstBufferPool used -by the decoder; free it after use it - - - - - a #GstVideoDecoder - - - - - - - - currently configured byte to time conversion setting - - - - - a #GstVideoDecoder - - - - - - Get a pending unfinished #GstVideoCodecFrame - - - pending unfinished #GstVideoCodecFrame identified by @frame_number. - - - - - a #GstVideoDecoder - - - - system_frame_number of a frame - - - - - - Get all pending unfinished #GstVideoCodecFrame - - - pending unfinished #GstVideoCodecFrame. - - - - - - - a #GstVideoDecoder - - - - - - Query the configured decoder latency. Results will be returned via -@min_latency and @max_latency. - - - - - - - a #GstVideoDecoder - - - - address of variable in which to store the - configured minimum latency, or %NULL - - - - address of variable in which to store the - configured mximum latency, or %NULL - - - - - - Determines maximum possible decoding time for @frame that will -allow it to decode and arrive in time (as determined by QoS events). -In particular, a negative result means decoding in time is no longer possible -and should therefore occur as soon/skippy as possible. - - - max decoding time. - - - - - a #GstVideoDecoder - - - - a #GstVideoCodecFrame - - - - - - - - currently configured decoder tolerated error count. - - - - - a #GstVideoDecoder - - - - - - Queries decoder required format handling. - - - %TRUE if required format handling is enabled. - - - - - a #GstVideoDecoder - - - - - - Get the oldest pending unfinished #GstVideoCodecFrame - - - oldest pending unfinished #GstVideoCodecFrame. - - - - - a #GstVideoDecoder - - - - - - Get the #GstVideoCodecState currently describing the output stream. - - - #GstVideoCodecState describing format of video data. - - - - - a #GstVideoDecoder - - - - - - Queries whether input data is considered packetized or not by the -base class. - - - TRUE if input data is considered packetized. - - - - - a #GstVideoDecoder - - - - - - Returns the number of bytes previously added to the current frame -by calling gst_video_decoder_add_to_frame(). - - - The number of bytes pending for the current frame - - - - - a #GstVideoDecoder - - - - - - - - The current QoS proportion. - - - - - a #GstVideoDecoder - current QoS proportion, or %NULL - - - - - - Gathers all data collected for currently parsed frame, gathers corresponding -metadata and passes it along for further processing, i.e. @handle_frame. - - - a #GstFlowReturn - - - - - a #GstVideoDecoder - - - - - - Sets the audio decoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with gst_audio_decoder_merge_tags(). - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. - - - - - - - a #GstVideoDecoder - - - - a #GstTagList to merge, or NULL to unset - previously-set tags - - - - the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE - - - - - - Negotiate with downstream elements to currently configured #GstVideoCodecState. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoDecoder - - - - - - Returns caps that express @caps (or sink template caps if @caps == NULL) -restricted to resolution/format/... combinations supported by downstream -elements. - - - a #GstCaps owned by caller - - - - - a #GstVideoDecoder - - - - initial caps - - - - filter caps - - - - - - Similar to gst_video_decoder_drop_frame(), but simply releases @frame -without any processing other than removing it from list of pending frames, -after which it is considered finished and released. - - - - - - - a #GstVideoDecoder - - - - the #GstVideoCodecFrame to release - - - - - - Allows baseclass to perform byte to time estimated conversion. - - - - - - - a #GstVideoDecoder - - - - whether to enable byte to time conversion - - - - - - Same as #gst_video_decoder_set_output_state() but also allows you to also set -the interlacing mode. - - - the newly configured output state. - - - - - a #GstVideoDecoder - - - - a #GstVideoFormat - - - - A #GstVideoInterlaceMode - - - - The width in pixels - - - - The height in pixels - - - - An optional reference #GstVideoCodecState - - - - - - Lets #GstVideoDecoder sub-classes tell the baseclass what the decoder -latency is. Will also post a LATENCY message on the bus so the pipeline -can reconfigure its global latency. - - - - - - - a #GstVideoDecoder - - - - minimum latency - - - - maximum latency - - - - - - Sets numbers of tolerated decoder errors, where a tolerated one is then only -warned about, but more than tolerated will lead to fatal error. You can set --1 for never returning fatal errors. Default is set to -GST_VIDEO_DECODER_MAX_ERRORS. - -The '-1' option was added in 1.4 - - - - - - - a #GstVideoDecoder - - - - max tolerated errors - - - - - - Configures decoder format needs. If enabled, subclass needs to be -negotiated with format caps before it can process any data. It will then -never be handed any data before it has been configured. -Otherwise, it might be handed data without having been configured and -is then expected being able to do so either by default -or based on the input data. - - - - - - - a #GstVideoDecoder - - - - new state - - - - - - Creates a new #GstVideoCodecState with the specified @fmt, @width and @height -as the output state for the decoder. -Any previously set output state on @decoder will be replaced by the newly -created one. - -If the subclass wishes to copy over existing fields (like pixel aspec ratio, -or framerate) from an existing #GstVideoCodecState, it can be provided as a -@reference. - -If the subclass wishes to override some fields from the output state (like -pixel-aspect-ratio or framerate) it can do so on the returned #GstVideoCodecState. - -The new output state will only take effect (set on pads and buffers) starting -from the next call to #gst_video_decoder_finish_frame(). - - - the newly configured output state. - - - - - a #GstVideoDecoder - - - - a #GstVideoFormat - - - - The width in pixels - - - - The height in pixels - - - - An optional reference #GstVideoCodecState - - - - - - Allows baseclass to consider input data as packetized or not. If the -input is packetized, then the @parse method will not be called. - - - - - - - a #GstVideoDecoder - - - - whether the input data should be considered as packetized. - - - - - - Lets #GstVideoDecoder sub-classes decide if they want the sink pad -to use the default pad query handler to reply to accept-caps queries. - -By setting this to true it is possible to further customize the default -handler with %GST_PAD_SET_ACCEPT_INTERSECT and -%GST_PAD_SET_ACCEPT_TEMPLATE - - - - - - - a #GstVideoDecoder - - - - if the default pad accept-caps query handling should be used - - - - - - Maximum number of tolerated consecutive decode errors. See -gst_video_decoder_set_max_errors() for more details. - - - - If set to %TRUE the decoder will handle QoS events received -from downstream elements. -This includes dropping output frames which are detected as late -using the metrics reported by those events. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum @handle_frame needs to be overridden, and @set_format -and likely as well. If non-packetized input is supported or expected, -@parse needs to be overridden as well. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoDecoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The interface allows unified access to control flipping and rotation -operations of video-sources or operators. - - - - - - - #GstVideoDirectionInterface interface. - - - parent interface type. - - - - - GstVideoDither provides implementations of several dithering algorithms -that can be applied to lines of video pixels to quantize and dither them. - - - Free @dither - - - - - - - a #GstVideoDither - - - - - - Dither @width pixels starting from offset @x in @line using @dither. - -@y is the line number of @line in the output image. - - - - - - - a #GstVideoDither - - - - pointer to the pixels of the line - - - - x coordinate - - - - y coordinate - - - - the width - - - - - - Make a new dither object for dithering lines of @format using the -algorithm described by @method. - -Each component will be quantized to a multiple of @quantizer. Better -performance is achieved when @quantizer is a power of 2. - -@width is the width of the lines that this ditherer will handle. - - - a new #GstVideoDither - - - - - a #GstVideoDitherMethod - - - - a #GstVideoDitherFlags - - - - a #GstVideoFormat - - - - quantizer - - - - the width of the lines - - - - - - - Extra flags that influence the result from gst_video_chroma_resample_new(). - - no flags - - - the input is interlaced - - - quantize values in addition to adding dither. - - - - Different dithering methods to use. - - no dithering - - - propagate rounding errors downwards - - - Dither with floyd-steinberg error diffusion - - - Dither with Sierra Lite error diffusion - - - ordered dither using a bayer pattern - - - - This base class is for video encoders turning raw video into -encoded video data. - -GstVideoEncoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstVideoEncoder calls @start when the encoder element - is activated, which allows subclass to perform any global setup. - * GstVideoEncoder calls @set_format to inform subclass of the format - of input video data that it is about to receive. Subclass should - setup for encoding and configure base class as appropriate - (e.g. latency). While unlikely, it might be called more than once, - if changing input parameters require reconfiguration. Baseclass - will ensure that processing of current configuration is finished. - * GstVideoEncoder calls @stop at end of all processing. - -## Data processing - - * Base class collects input data and metadata into a frame and hands - this to subclass' @handle_frame. - - * If codec processing results in encoded data, subclass should call - @gst_video_encoder_finish_frame to have encoded data pushed - downstream. - - * If implemented, baseclass calls subclass @pre_push just prior to - pushing to allow subclasses to modify some metadata on the buffer. - If it returns GST_FLOW_OK, the buffer is pushed downstream. - - * GstVideoEncoderClass will handle both srcpad and sinkpad events. - Sink events will be passed to subclass if @event callback has been - provided. - -## Shutdown phase - - * GstVideoEncoder class calls @stop to inform the subclass that data - parsing will be stopped. - -Subclass is responsible for providing pad template caps for -source and sink pads. The pads need to be named "sink" and "src". It should -also be able to provide fixed src pad caps in @getcaps by the time it calls -@gst_video_encoder_finish_frame. - -Things that subclass need to take care of: - - * Provide pad templates - * Provide source pad caps before pushing the first buffer - * Accept data in @handle_frame and provide encoded results to - @gst_video_encoder_finish_frame. - - -The #GstVideoEncoder:qos property will enable the Quality-of-Service -features of the encoder which gather statistics about the real-time -performance of the downstream elements. If enabled, subclasses can -use gst_video_encoder_get_max_encode_time() to check if input frames -are already late and drop them right away to give a chance to the -pipeline to catch up. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Negotiate with downstream elements to currently configured #GstVideoCodecState. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoEncoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Helper function that allocates a buffer to hold an encoded video frame -for @encoder's current #GstVideoCodecState. - - - allocated buffer - - - - - a #GstVideoEncoder - - - - size of the buffer - - - - - - Helper function that allocates a buffer to hold an encoded video frame for @encoder's -current #GstVideoCodecState. Subclass should already have configured video -state and set src pad caps. - -The buffer allocated here is owned by the frame and you should only -keep references to the frame, not the buffer. - - - %GST_FLOW_OK if an output buffer could be allocated - - - - - a #GstVideoEncoder - - - - a #GstVideoCodecFrame - - - - size of the buffer - - - - - - @frame must have a valid encoded data buffer, whose metadata fields -are then appropriately set according to frame data or no buffer at -all if the frame should be dropped. -It is subsequently pushed downstream or provided to @pre_push. -In any case, the frame is considered finished and released. - -After calling this function the output buffer of the frame is to be -considered read-only. This function will also change the metadata -of the buffer. - - - a #GstFlowReturn resulting from sending data downstream - - - - - a #GstVideoEncoder - - - - an encoded #GstVideoCodecFrame - - - - - - If multiple subframes are produced for one input frame then use this method -for each subframe, except for the last one. Before calling this function, -you need to fill frame->output_buffer with the encoded buffer to push. - -You must call #gst_video_encoder_finish_frame() for the last sub-frame -to tell the encoder that the frame has been fully encoded. - -This function will change the metadata of @frame and frame->output_buffer -will be pushed downstream. - - - a #GstFlowReturn resulting from pushing the buffer downstream. - - - - - a #GstVideoEncoder - - - - a #GstVideoCodecFrame being encoded - - - - - - Lets #GstVideoEncoder sub-classes to know the memory @allocator -used by the base class and its @params. - -Unref the @allocator after use it. - - - - - - - a #GstVideoEncoder - - - - the #GstAllocator -used - - - - the -#GstAllocationParams of @allocator - - - - - - Get a pending unfinished #GstVideoCodecFrame - - - pending unfinished #GstVideoCodecFrame identified by @frame_number. - - - - - a #GstVideoEncoder - - - - system_frame_number of a frame - - - - - - Get all pending unfinished #GstVideoCodecFrame - - - pending unfinished #GstVideoCodecFrame. - - - - - - - a #GstVideoEncoder - - - - - - Query the configured encoding latency. Results will be returned via -@min_latency and @max_latency. - - - - - - - a #GstVideoEncoder - - - - address of variable in which to store the - configured minimum latency, or %NULL - - - - address of variable in which to store the - configured maximum latency, or %NULL - - - - - - Determines maximum possible encoding time for @frame that will -allow it to encode and arrive in time (as determined by QoS events). -In particular, a negative result means encoding in time is no longer possible -and should therefore occur as soon/skippy as possible. - -If no QoS events have been received from downstream, or if -#GstVideoEncoder:qos is disabled this function returns #G_MAXINT64. - - - max decoding time. - - - - - a #GstVideoEncoder - - - - a #GstVideoCodecFrame - - - - - - Returns the minimum force-keyunit interval, see gst_video_encoder_set_min_force_key_unit_interval() -for more details. - - - the minimum force-keyunit interval - - - - - the encoder - - - - - - Get the oldest unfinished pending #GstVideoCodecFrame - - - oldest unfinished pending #GstVideoCodecFrame - - - - - a #GstVideoEncoder - - - - - - Get the current #GstVideoCodecState - - - #GstVideoCodecState describing format of video data. - - - - - a #GstVideoEncoder - - - - - - Checks if @encoder is currently configured to handle Quality-of-Service -events from downstream. - - - %TRUE if the encoder is configured to perform Quality-of-Service. - - - - - the encoder - - - - - - Sets the video encoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with gst_video_encoder_merge_tags(). - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. - - - - - - - a #GstVideoEncoder - - - - a #GstTagList to merge, or NULL to unset - previously-set tags - - - - the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE - - - - - - Negotiate with downstream elements to currently configured #GstVideoCodecState. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoEncoder - - - - - - Returns caps that express @caps (or sink template caps if @caps == NULL) -restricted to resolution/format/... combinations supported by downstream -elements (e.g. muxers). - - - a #GstCaps owned by caller - - - - - a #GstVideoEncoder - - - - initial caps - - - - filter caps - - - - - - Set the codec headers to be sent downstream whenever requested. - - - - - - - a #GstVideoEncoder - - - - a list of #GstBuffer containing the codec header - - - - - - - - Informs baseclass of encoding latency. - - - - - - - a #GstVideoEncoder - - - - minimum latency - - - - maximum latency - - - - - - Sets the minimum interval for requesting keyframes based on force-keyunit -events. Setting this to 0 will allow to handle every event, setting this to -%GST_CLOCK_TIME_NONE causes force-keyunit events to be ignored. - - - - - - - the encoder - - - - minimum interval - - - - - - Request minimal value for PTS passed to handle_frame. - -For streams with reordered frames this can be used to ensure that there -is enough time to accommodate first DTS, which may be less than first PTS - - - - - - - a #GstVideoEncoder - - - - minimal PTS that will be passed to handle_frame - - - - - - Creates a new #GstVideoCodecState with the specified caps as the output state -for the encoder. -Any previously set output state on @encoder will be replaced by the newly -created one. - -The specified @caps should not contain any resolution, pixel-aspect-ratio, -framerate, codec-data, .... Those should be specified instead in the returned -#GstVideoCodecState. - -If the subclass wishes to copy over existing fields (like pixel aspect ratio, -or framerate) from an existing #GstVideoCodecState, it can be provided as a -@reference. - -If the subclass wishes to override some fields from the output state (like -pixel-aspect-ratio or framerate) it can do so on the returned #GstVideoCodecState. - -The new output state will only take effect (set on pads and buffers) starting -from the next call to #gst_video_encoder_finish_frame(). - - - the newly configured output state. - - - - - a #GstVideoEncoder - - - - the #GstCaps to use for the output - - - - An optional reference @GstVideoCodecState - - - - - - Configures @encoder to handle Quality-of-Service events from downstream. - - - - - - - the encoder - - - - the new qos value. - - - - - - Minimum interval between force-keyunit requests in nanoseconds. See -gst_video_encoder_set_min_force_key_unit_interval() for more details. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Subclasses can override any of the available virtual methods or not, as -needed. At minimum @handle_frame needs to be overridden, and @set_format -and @get_caps are likely needed as well. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %TRUE if the negotiation succeeded, else %FALSE. - - - - - a #GstVideoEncoder - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Field order of interlaced content. This is only valid for -interlace-mode=interleaved and not interlace-mode=mixed. In the case of -mixed or GST_VIDEO_FIELD_ORDER_UNKOWN, the field order is signalled via -buffer flags. - - unknown field order for interlaced content. - The actual field order is signalled via buffer flags. - - - top field is first - - - bottom field is first - - - Convert @order to a #GstVideoFieldOrder - - - the #GstVideoFieldOrder of @order or - #GST_VIDEO_FIELD_ORDER_UNKNOWN when @order is not a valid - string representation for a #GstVideoFieldOrder. - - - - - a field order - - - - - - Convert @order to its string representation. - - - @order as a string or NULL if @order in invalid. - - - - - a #GstVideoFieldOrder - - - - - - - Provides useful functions and a base class for video filters. - -The videofilter will by default enable QoS on the parent GstBaseTransform -to implement frame dropping. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The video filter class structure. - - - the parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extra video flags - - no flags - - - a variable fps is selected, fps_n and fps_d - denote the maximum fps of the video - - - Each color has been scaled by the alpha - value. - - - - Enum value describing the most common video formats. - -See the [GStreamer raw video format design document](https://gstreamer.freedesktop.org/documentation/additional/design/mediatype-video-raw.html#formats) -for details about the layout and packing of these formats in memory. - - Unknown or unset video format id - - - Encoded video format. Only ever use that in caps for - special video formats in combination with non-system - memory GstCapsFeatures where it does not make sense - to specify a real video format. - - - planar 4:2:0 YUV - - - planar 4:2:0 YVU (like I420 but UV planes swapped) - - - packed 4:2:2 YUV (Y0-U0-Y1-V0 Y2-U2-Y3-V2 Y4 ...) - - - packed 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...) - - - packed 4:4:4 YUV with alpha channel (A0-Y0-U0-V0 ...) - - - sparse rgb packed into 32 bit, space last - - - sparse reverse rgb packed into 32 bit, space last - - - sparse rgb packed into 32 bit, space first - - - sparse reverse rgb packed into 32 bit, space first - - - rgb with alpha channel last - - - reverse rgb with alpha channel last - - - rgb with alpha channel first - - - reverse rgb with alpha channel first - - - RGB packed into 24 bits without padding (`R-G-B-R-G-B`) - - - reverse RGB packed into 24 bits without padding (`B-G-R-B-G-R`) - - - planar 4:1:1 YUV - - - planar 4:2:2 YUV - - - packed 4:2:2 YUV (Y0-V0-Y1-U0 Y2-V2-Y3-U2 Y4 ...) - - - planar 4:4:4 YUV - - - packed 4:2:2 10-bit YUV, complex format - - - packed 4:2:2 16-bit YUV, Y0-U0-Y1-V1 order - - - planar 4:2:0 YUV with interleaved UV plane - - - planar 4:2:0 YUV with interleaved VU plane - - - 8-bit grayscale - - - 16-bit grayscale, most significant byte first - - - 16-bit grayscale, least significant byte first - - - packed 4:4:4 YUV (Y-U-V ...) - - - rgb 5-6-5 bits per component - - - reverse rgb 5-6-5 bits per component - - - rgb 5-5-5 bits per component - - - reverse rgb 5-5-5 bits per component - - - packed 10-bit 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...) - - - planar 4:4:2:0 AYUV - - - 8-bit paletted RGB - - - planar 4:1:0 YUV - - - planar 4:1:0 YUV (like YUV9 but UV planes swapped) - - - packed 4:1:1 YUV (Cb-Y0-Y1-Cr-Y2-Y3 ...) - - - rgb with alpha channel first, 16 bits per channel - - - packed 4:4:4 YUV with alpha channel, 16 bits per channel (A0-Y0-U0-V0 ...) - - - packed 4:4:4 RGB, 10 bits per channel - - - planar 4:2:0 YUV, 10 bits per channel - - - planar 4:2:0 YUV, 10 bits per channel - - - planar 4:2:2 YUV, 10 bits per channel - - - planar 4:2:2 YUV, 10 bits per channel - - - planar 4:4:4 YUV, 10 bits per channel (Since: 1.2) - - - planar 4:4:4 YUV, 10 bits per channel (Since: 1.2) - - - planar 4:4:4 RGB, 8 bits per channel (Since: 1.2) - - - planar 4:4:4 RGB, 10 bits per channel (Since: 1.2) - - - planar 4:4:4 RGB, 10 bits per channel (Since: 1.2) - - - planar 4:2:2 YUV with interleaved UV plane (Since: 1.2) - - - planar 4:4:4 YUV with interleaved UV plane (Since: 1.2) - - - NV12 with 64x32 tiling in zigzag pattern (Since: 1.4) - - - planar 4:4:2:0 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:4:2:0 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:4:2:2 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:4:2:2 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:4:4:4 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:4:4:4 YUV, 10 bits per channel (Since: 1.6) - - - planar 4:2:2 YUV with interleaved VU plane (Since: 1.6) - - - planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) - - - planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) - - - packed 4:4:4 YUV (U-Y-V ...) (Since: 1.10) - - - packed 4:2:2 YUV (V0-Y0-U0-Y1 V2-Y2-U2-Y3 V4 ...) - - - planar 4:4:4:4 ARGB, 8 bits per channel (Since: 1.12) - - - planar 4:4:4:4 ARGB, 10 bits per channel (Since: 1.12) - - - planar 4:4:4:4 ARGB, 10 bits per channel (Since: 1.12) - - - planar 4:4:4 RGB, 12 bits per channel (Since: 1.12) - - - planar 4:4:4 RGB, 12 bits per channel (Since: 1.12) - - - planar 4:4:4:4 ARGB, 12 bits per channel (Since: 1.12) - - - planar 4:4:4:4 ARGB, 12 bits per channel (Since: 1.12) - - - planar 4:2:0 YUV, 12 bits per channel (Since: 1.12) - - - planar 4:2:0 YUV, 12 bits per channel (Since: 1.12) - - - planar 4:2:2 YUV, 12 bits per channel (Since: 1.12) - - - planar 4:2:2 YUV, 12 bits per channel (Since: 1.12) - - - planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) - - - planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) - - - 10-bit grayscale, packed into 32bit words (2 bits padding) (Since: 1.14) - - - 10-bit variant of @GST_VIDEO_FORMAT_NV12, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) - - - 10-bit variant of @GST_VIDEO_FORMAT_NV16, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) - - - Fully packed variant of NV12_10LE32 (Since: 1.16) - - - packed 4:2:2 YUV, 10 bits per channel (Since: 1.16) - - - packed 4:4:4 YUV, 10 bits per channel(A-V-Y-U...) (Since: 1.16) - - - packed 4:4:4 YUV with alpha channel (V0-U0-Y0-A0...) (Since: 1.16) - - - packed 4:4:4 RGB with alpha channel(B-G-R-A), 10 bits for R/G/B channel and MSB 2 bits for alpha channel (Since: 1.16) - - - packed 4:4:4 RGB with alpha channel(R-G-B-A), 10 bits for R/G/B channel and MSB 2 bits for alpha channel (Since: 1.18) - - - planar 4:4:4 YUV, 16 bits per channel (Since: 1.18) - - - planar 4:4:4 YUV, 16 bits per channel (Since: 1.18) - - - planar 4:2:0 YUV with interleaved UV plane, 16 bits per channel (Since: 1.18) - - - planar 4:2:0 YUV with interleaved UV plane, 16 bits per channel (Since: 1.18) - - - planar 4:2:0 YUV with interleaved UV plane, 12 bits per channel (Since: 1.18) - - - planar 4:2:0 YUV with interleaved UV plane, 12 bits per channel (Since: 1.18) - - - packed 4:2:2 YUV, 12 bits per channel (Y-U-Y-V) (Since: 1.18) - - - packed 4:2:2 YUV, 12 bits per channel (Y-U-Y-V) (Since: 1.18) - - - packed 4:4:4:4 YUV, 12 bits per channel(U-Y-V-A...) (Since: 1.18) - - - packed 4:4:4:4 YUV, 12 bits per channel(U-Y-V-A...) (Since: 1.18) - - - NV12 with 4x4 tiles in linear order (Since: 1.18) - - - NV12 with 32x32 tiles in linear order (Since: 1.18) - - - Converts a FOURCC value into the corresponding #GstVideoFormat. -If the FOURCC cannot be represented by #GstVideoFormat, -#GST_VIDEO_FORMAT_UNKNOWN is returned. - - - the #GstVideoFormat describing the FOURCC value - - - - - a FOURCC value representing raw YUV video - - - - - - Find the #GstVideoFormat for the given parameters. - - - a #GstVideoFormat or GST_VIDEO_FORMAT_UNKNOWN when the parameters to -not specify a known format. - - - - - the amount of bits used for a pixel - - - - the amount of bits used to store a pixel. This value is bigger than - @depth - - - - the endianness of the masks, #G_LITTLE_ENDIAN or #G_BIG_ENDIAN - - - - the red mask - - - - the green mask - - - - the blue mask - - - - the alpha mask, or 0 if no alpha mask - - - - - - Convert the @format string to its #GstVideoFormat. - - - the #GstVideoFormat for @format or GST_VIDEO_FORMAT_UNKNOWN when the -string is not a known format. - - - - - a format string - - - - - - Get the #GstVideoFormatInfo for @format - - - The #GstVideoFormatInfo for @format. - - - - - a #GstVideoFormat - - - - - - Get the default palette of @format. This the palette used in the pack -function for paletted formats. - - - the default palette of @format or %NULL when -@format does not have a palette. - - - - - a #GstVideoFormat - - - - size of the palette in bytes - - - - - - Converts a #GstVideoFormat value into the corresponding FOURCC. Only -a few YUV formats have corresponding FOURCC values. If @format has -no corresponding FOURCC value, 0 is returned. - - - the FOURCC corresponding to @format - - - - - a #GstVideoFormat video format - - - - - - Returns a string containing a descriptive name for -the #GstVideoFormat if there is one, or NULL otherwise. - - - the name corresponding to @format - - - - - a #GstVideoFormat video format - - - - - - - The different video flags that a format info can have. - - The video format is YUV, components are numbered - 0=Y, 1=U, 2=V. - - - The video format is RGB, components are numbered - 0=R, 1=G, 2=B. - - - The video is gray, there is one gray component - with index 0. - - - The video format has an alpha components with - the number 3. - - - The video format has data stored in little - endianness. - - - The video format has a palette. The palette - is stored in the second plane and indexes are stored in the first plane. - - - The video format has a complex layout that - can't be described with the usual information in the #GstVideoFormatInfo. - - - This format can be used in a - #GstVideoFormatUnpack and #GstVideoFormatPack function. - - - The format is tiled, there is tiling information - in the last plane. - - - - Information for a video format. - - - #GstVideoFormat - - - - string representation of the format - - - - use readable description of the format - - - - #GstVideoFormatFlags - - - - The number of bits used to pack data items. This can be less than 8 - when multiple pixels are stored in a byte. for values > 8 multiple bytes - should be read according to the endianness flag before applying the shift - and mask. - - - - the number of components in the video format. - - - - the number of bits to shift away to get the component data - - - - - - the depth in bits for each component - - - - - - the pixel stride of each component. This is the amount of - bytes to the pixel immediately to the right. When bits < 8, the stride is - expressed in bits. For 24-bit RGB, this would be 3 bytes, for example, - while it would be 4 bytes for RGBx or ARGB. - - - - - - the number of planes for this format. The number of planes can be - less than the amount of components when multiple components are packed into - one plane. - - - - the plane number where a component can be found - - - - - - the offset in the plane where the first pixel of the components - can be found. - - - - - - subsampling factor of the width for the component. Use - GST_VIDEO_SUB_SCALE to scale a width. - - - - - - subsampling factor of the height for the component. Use - GST_VIDEO_SUB_SCALE to scale a height. - - - - - - the format of the unpacked pixels. This format must have the - #GST_VIDEO_FORMAT_FLAG_UNPACK flag set. - - - - an unpack function for this format - - - - the amount of lines that will be packed - - - - an pack function for this format - - - - The tiling mode - - - - The width of a tile, in bytes, represented as a shift - - - - The height of a tile, in bytes, represented as a shift - - - - - - - - - Fill @components with the number of all the components packed in plane @p -for the format @info. A value of -1 in @components indicates that no more -components are packed in the plane. - - - - - - - #GstVideoFormatInfo - - - - a plane number - - - - array used to store component numbers - - - - - - - Packs @width pixels from @src to the given planes and strides in the -format @info. The pixels from source have each component interleaved -and will be packed into the planes in @data. - -This function operates on pack_lines lines, meaning that @src should -contain at least pack_lines lines with a stride of @sstride and @y -should be a multiple of pack_lines. - -Subsampled formats will use the horizontally and vertically cosited -component from the source. Subsampling should be performed before -packing. - -Because this function does not have a x coordinate, it is not possible to -pack pixels starting from an unaligned position. For tiled images this -means that packing should start from a tile coordinate. For subsampled -formats this means that a complete pixel needs to be packed. - - - - - - - a #GstVideoFormatInfo - - - - flags to control the packing - - - - a source array - - - - the source array stride - - - - pointers to the destination data planes - - - - strides of the destination planes - - - - the chroma siting of the target when subsampled (not used) - - - - the y position in the image to pack to - - - - the amount of pixels to pack. - - - - - - Unpacks @width pixels from the given planes and strides containing data of -format @info. The pixels will be unpacked into @dest with each component -interleaved as per @info's unpack_format, which will usually be one of -#GST_VIDEO_FORMAT_ARGB, #GST_VIDEO_FORMAT_AYUV, #GST_VIDEO_FORMAT_ARGB64 or -#GST_VIDEO_FORMAT_AYUV64 depending on the format to unpack. -@dest should at least be big enough to hold @width * bytes_per_pixel bytes -where bytes_per_pixel relates to the unpack format and will usually be -either 4 or 8 depending on the unpack format. bytes_per_pixel will be -the same as the pixel stride for plane 0 for the above formats. - -For subsampled formats, the components will be duplicated in the destination -array. Reconstruction of the missing components can be performed in a -separate step after unpacking. - - - - - - - a #GstVideoFormatInfo - - - - flags to control the unpacking - - - - a destination array - - - - pointers to the data planes - - - - strides of the planes - - - - the x position in the image to start from - - - - the y position in the image to start from - - - - the amount of pixels to unpack. - - - - - - A video frame obtained from gst_video_frame_map() - - - the #GstVideoInfo - - - - #GstVideoFrameFlags for the frame - - - - the mapped buffer - - - - pointer to metadata if any - - - - id of the mapped frame. the id can for example be used to - identify the frame in case of multiview video. - - - - pointers to the plane data - - - - - - mappings of the planes - - - - - - - - - - - Copy the contents from @src to @dest. - -Note: Since: 1.18, @dest dimensions are allowed to be -smaller than @src dimensions. - - - TRUE if the contents could be copied. - - - - - a #GstVideoFrame - - - - a #GstVideoFrame - - - - - - Copy the plane with index @plane from @src to @dest. - -Note: Since: 1.18, @dest dimensions are allowed to be -smaller than @src dimensions. - - - TRUE if the contents could be copied. - - - - - a #GstVideoFrame - - - - a #GstVideoFrame - - - - a plane - - - - - - Use @info and @buffer to fill in the values of @frame. @frame is usually -allocated on the stack, and you will pass the address to the #GstVideoFrame -structure allocated on the stack; gst_video_frame_map() will then fill in -the structures with the various video-specific information you need to access -the pixels of the video buffer. You can then use accessor macros such as -GST_VIDEO_FRAME_COMP_DATA(), GST_VIDEO_FRAME_PLANE_DATA(), -GST_VIDEO_FRAME_COMP_STRIDE(), GST_VIDEO_FRAME_PLANE_STRIDE() etc. -to get to the pixels. - -|[<!-- language="C" --> - GstVideoFrame vframe; - ... - // set RGB pixels to black one at a time - if (gst_video_frame_map (&amp;vframe, video_info, video_buffer, GST_MAP_WRITE)) { - guint8 *pixels = GST_VIDEO_FRAME_PLANE_DATA (vframe, 0); - guint stride = GST_VIDEO_FRAME_PLANE_STRIDE (vframe, 0); - guint pixel_stride = GST_VIDEO_FRAME_COMP_PSTRIDE (vframe, 0); - - for (h = 0; h < height; ++h) { - for (w = 0; w < width; ++w) { - guint8 *pixel = pixels + h * stride + w * pixel_stride; - - memset (pixel, 0, pixel_stride); - } - } - - gst_video_frame_unmap (&amp;vframe); - } - ... -]| - -All video planes of @buffer will be mapped and the pointers will be set in -@frame->data. - -The purpose of this function is to make it easy for you to get to the video -pixels in a generic way, without you having to worry too much about details -such as whether the video data is allocated in one contiguous memory chunk -or multiple memory chunks (e.g. one for each plane); or if custom strides -and custom plane offsets are used or not (as signalled by GstVideoMeta on -each buffer). This function will just fill the #GstVideoFrame structure -with the right values and if you use the accessor macros everything will -just work and you can access the data easily. It also maps the underlying -memory chunks for you. - - - %TRUE on success. - - - - - pointer to #GstVideoFrame - - - - a #GstVideoInfo - - - - the buffer to map - - - - #GstMapFlags - - - - - - Use @info and @buffer to fill in the values of @frame with the video frame -information of frame @id. - -When @id is -1, the default frame is mapped. When @id != -1, this function -will return %FALSE when there is no GstVideoMeta with that id. - -All video planes of @buffer will be mapped and the pointers will be set in -@frame->data. - - - %TRUE on success. - - - - - pointer to #GstVideoFrame - - - - a #GstVideoInfo - - - - the buffer to map - - - - the frame id to map - - - - #GstMapFlags - - - - - - Unmap the memory previously mapped with gst_video_frame_map. - - - - - - - a #GstVideoFrame - - - - - - - Extra video frame flags - - no flags - - - The video frame is interlaced. In mixed - interlace-mode, this flag specifies if the frame is interlaced or - progressive. - - - The video frame has the top field first - - - The video frame has the repeat flag - - - The video frame has one field - - - The video contains one or - more non-mono views - - - The video frame is the first - in a set of corresponding views provided as sequential frames. - - - The video frame has the top field only. This - is the same as GST_VIDEO_FRAME_FLAG_TFF | GST_VIDEO_FRAME_FLAG_ONEFIELD - (Since: 1.16). - - - The video frame has the bottom field - only. This is the same as GST_VIDEO_FRAME_FLAG_ONEFIELD - (GST_VIDEO_FRAME_FLAG_TFF flag unset) (Since: 1.16). - - - - Additional mapping flags for gst_video_frame_map(). - - Don't take another reference of the buffer and store it in - the GstVideoFrame. This makes sure that the buffer stays - writable while the frame is mapped, but requires that the - buffer reference stays valid until the frame is unmapped again. - - - Offset to define more flags - - - - The orientation of the GL texture. - - - Top line first in memory, left row first - - - Bottom line first in memory, left row first - - - Top line first in memory, right row first - - - Bottom line first in memory, right row first - - - - The GL texture type. - - - Luminance texture, GL_LUMINANCE - - - Luminance-alpha texture, GL_LUMINANCE_ALPHA - - - RGB 565 texture, GL_RGB - - - RGB texture, GL_RGB - - - RGBA texture, GL_RGBA - - - R texture, GL_RED_EXT - - - RG texture, GL_RG_EXT - - - - - - - - - - - - - - - - - - Extra buffer metadata for uploading a buffer to an OpenGL texture -ID. The caller of gst_video_gl_texture_upload_meta_upload() must -have OpenGL set up and call this from a thread where it is valid -to upload something to an OpenGL texture. - - - parent #GstMeta - - - - Orientation of the textures - - - - Number of textures that are generated - - - - Type of each texture - - - - - - - - - - - - - - - - - - - - - Uploads the buffer which owns the meta to a specific texture ID. - - - %TRUE if uploading succeeded, %FALSE otherwise. - - - - - a #GstVideoGLTextureUploadMeta - - - - the texture IDs to upload to - - - - - - - - - - - - - - disable gamma handling - - - convert between input and output gamma -Different gamma conversion modes - - - - Information describing image properties. This information can be filled -in from GstCaps with gst_video_info_from_caps(). The information is also used -to store the specific video info when mapping a video frame with -gst_video_frame_map(). - -Use the provided macros to access the info in this structure. - - - the format info of the video - - - - the interlace mode - - - - additional video flags - - - - the width of the video - - - - the height of the video - - - - the default size of one frame - - - - the number of views for multiview video - - - - a #GstVideoChromaSite. - - - - the colorimetry info - - - - the pixel-aspect-ratio numerator - - - - the pixel-aspect-ratio denominator - - - - the framerate numerator - - - - the framerate denominator - - - - offsets of the planes - - - - - - strides of the planes - - - - - - - - - - - - - - - - - - - - - - - - - - Allocate a new #GstVideoInfo that is also initialized with -gst_video_info_init(). - - - a new #GstVideoInfo. free with gst_video_info_free(). - - - - - Adjust the offset and stride fields in @info so that the padding and -stride alignment in @align is respected. - -Extra padding will be added to the right side when stride alignment padding -is required and @align will be updated with the new padding values. - - - %FALSE if alignment could not be applied, e.g. because the - size of a frame can't be represented as a 32 bit integer (Since: 1.12) - - - - - a #GstVideoInfo - - - - alignment parameters - - - - - - This variant of gst_video_info_align() provides the updated size, in bytes, -of each video plane after the alignment, including all horizontal and vertical -paddings. - -In case of GST_VIDEO_INTERLACE_MODE_ALTERNATE info, the returned sizes are the -ones used to hold a single field, not the full frame. - - - %FALSE if alignment could not be applied, e.g. because the - size of a frame can't be represented as a 32 bit integer - - - - - a #GstVideoInfo - - - - alignment parameters - - - - array used to store the plane sizes - - - - - - Converts among various #GstFormat types. This function handles -GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For -raw video, GST_FORMAT_DEFAULT corresponds to video frames. This -function can be used to handle pad queries of the type GST_QUERY_CONVERT. - - - TRUE if the conversion was successful. - - - - - a #GstVideoInfo - - - - #GstFormat of the @src_value - - - - value to convert - - - - #GstFormat of the @dest_value - - - - pointer to destination value - - - - - - Copy a GstVideoInfo structure. - - - a new #GstVideoInfo. free with gst_video_info_free. - - - - - a #GstVideoInfo - - - - - - Free a GstVideoInfo structure previously allocated with gst_video_info_new() -or gst_video_info_copy(). - - - - - - - a #GstVideoInfo - - - - - - Parse @caps and update @info. - - - TRUE if @caps could be parsed - - - - - a #GstVideoInfo - - - - a #GstCaps - - - - - - Initialize @info with default values. - - - - - - - a #GstVideoInfo - - - - - - Compares two #GstVideoInfo and returns whether they are equal or not - - - %TRUE if @info and @other are equal, else %FALSE. - - - - - a #GstVideoInfo - - - - a #GstVideoInfo - - - - - - Set the default info for a video frame of @format and @width and @height. - -Note: This initializes @info first, no values are preserved. This function -does not set the offsets correctly for interlaced vertically -subsampled formats. - - - %FALSE if the returned video info is invalid, e.g. because the - size of a frame can't be represented as a 32 bit integer (Since: 1.12) - - - - - a #GstVideoInfo - - - - the format - - - - a width - - - - a height - - - - - - Same as #gst_video_info_set_format but also allowing to set the interlaced -mode. - - - %FALSE if the returned video info is invalid, e.g. because the - size of a frame can't be represented as a 32 bit integer. - - - - - a #GstVideoInfo - - - - the format - - - - a #GstVideoInterlaceMode - - - - a width - - - - a height - - - - - - Convert the values of @info into a #GstCaps. - - - a new #GstCaps containing the info of @info. - - - - - a #GstVideoInfo - - - - - - - The possible values of the #GstVideoInterlaceMode describing the interlace -mode of the stream. - - all frames are progressive - - - 2 fields are interleaved in one video - frame. Extra buffer flags describe the field order. - - - frames contains both interlaced and - progressive video, the buffer flags describe the frame and fields. - - - 2 fields are stored in one buffer, use the - frame ID to get access to the required field. For multiview (the - 'views' property > 1) the fields of view N can be found at frame ID - (N * 2) and (N * 2) + 1. - Each field has only half the amount of lines as noted in the - height property. This mode requires multiple GstVideoMeta metadata - to describe the fields. - - - 1 field is stored in one buffer, - @GST_VIDEO_BUFFER_FLAG_TF or @GST_VIDEO_BUFFER_FLAG_BF indicates if - the buffer is carrying the top or bottom field, respectively. The top and - bottom buffers are expected to alternate in the pipeline, with this mode - (Since: 1.16). - - - Convert @mode to a #GstVideoInterlaceMode - - - the #GstVideoInterlaceMode of @mode or - #GST_VIDEO_INTERLACE_MODE_PROGRESSIVE when @mode is not a valid - string representation for a #GstVideoInterlaceMode. - - - - - a mode - - - - - - Convert @mode to its string representation. - - - @mode as a string or NULL if @mode in invalid. - - - - - a #GstVideoInterlaceMode - - - - - - - Mastering display color volume information defined by SMPTE ST 2086 -(a.k.a static HDR metadata). - - - the xy coordinates of primaries in the CIE 1931 color space. - the index 0 contains red, 1 is for green and 2 is for blue. - each value is normalized to 50000 (meaning that in unit of 0.00002) - - - - - - the xy coordinates of white point in the CIE 1931 color space. - each value is normalized to 50000 (meaning that in unit of 0.00002) - - - - the maximum value of display luminance - in unit of 0.0001 candelas per square metre (cd/m^2 and nit) - - - - the minimum value of display luminance - in unit of 0.0001 candelas per square metre (cd/m^2 and nit) - - - - - - - - - Set string representation of @minfo to @caps - - - %TRUE if @minfo was successfully set to @caps - - - - - a #GstVideoMasteringDisplayInfo - - - - a #GstCaps - - - - - - Parse @caps and update @minfo - - - %TRUE if @caps has #GstVideoMasteringDisplayInfo and could be parsed - - - - - a #GstVideoMasteringDisplayInfo - - - - a #GstCaps - - - - - - Initialize @minfo - - - - - - - a #GstVideoMasteringDisplayInfo - - - - - - Checks equality between @minfo and @other. - - - %TRUE if @minfo and @other are equal. - - - - - a #GstVideoMasteringDisplayInfo - - - - a #GstVideoMasteringDisplayInfo - - - - - - Convert @minfo to its string representation - - - a string representation of @minfo - - - - - a #GstVideoMasteringDisplayInfo - - - - - - Extract #GstVideoMasteringDisplayInfo from @mastering - - - %TRUE if @minfo was filled with @mastering - - - - - a #GstVideoMasteringDisplayInfo - - - - a #GstStructure representing #GstVideoMasteringDisplayInfo - - - - - - - Used to represent display_primaries and white_point of -#GstVideoMasteringDisplayInfo struct. See #GstVideoMasteringDisplayInfo - - - the x coordinate of CIE 1931 color space in unit of 0.00002. - - - - the y coordinate of CIE 1931 color space in unit of 0.00002. - - - - - Different color matrix conversion modes - - do conversion between color matrices - - - use the input color matrix to convert - to and from R'G'B - - - use the output color matrix to convert - to and from R'G'B - - - disable color matrix conversion. - - - - Extra buffer metadata describing image properties - -This meta can also be used by downstream elements to specifiy their -buffer layout requirements for upstream. Upstream should try to -fit those requirements, if possible, in order to prevent buffer copies. - -This is done by passing a custom #GstStructure to -gst_query_add_allocation_meta() when handling the ALLOCATION query. -This structure should be named 'video-meta' and can have the following -fields: -- padding-top (uint): extra pixels on the top -- padding-bottom (uint): extra pixels on the bottom -- padding-left (uint): extra pixels on the left side -- padding-right (uint): extra pixels on the right side -The padding fields have the same semantic as #GstVideoMeta.alignment -and so represent the paddings requested on produced video buffers. - - - parent #GstMeta - - - - the buffer this metadata belongs to - - - - additional video flags - - - - the video format - - - - identifier of the frame - - - - the video width - - - - the video height - - - - the number of planes in the image - - - - array of offsets for the planes. This field might not always be - valid, it is used by the default implementation of @map. - - - - - - array of strides for the planes. This field might not always be - valid, it is used by the default implementation of @map. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - the paddings and alignment constraints of the video buffer. -It is up to the caller of `gst_buffer_add_video_meta_full()` to set it -using gst_video_meta_set_alignment(), if they did not it defaults -to no padding and no alignment. Since: 1.18 - - - - Compute the padded height of each plane from @meta (padded size -divided by stride). - -It is not valid to call this function with a meta associated to a -TILED video format. - - - %TRUE if @meta's alignment is valid and @plane_height has been -updated, %FALSE otherwise - - - - - a #GstVideoMeta - - - - array used to store the plane height - - - - - - Compute the size, in bytes, of each video plane described in @meta including -any padding and alignment constraint defined in @meta->alignment. - - - %TRUE if @meta's alignment is valid and @plane_size has been -updated, %FALSE otherwise - - - - - a #GstVideoMeta - - - - array used to store the plane sizes - - - - - - Map the video plane with index @plane in @meta and return a pointer to the -first byte of the plane and the stride of the plane. - - - TRUE if the map operation was successful. - - - - - a #GstVideoMeta - - - - a plane - - - - a #GstMapInfo - - - - the data of @plane - - - - the stride of @plane - - - - @GstMapFlags - - - - - - Set the alignment of @meta to @alignment. This function checks that -the paddings defined in @alignment are compatible with the strides -defined in @meta and will fail to update if they are not. - - - %TRUE if @alignment's meta has been updated, %FALSE if not - - - - - a #GstVideoMeta - - - - a #GstVideoAlignment - - - - - - Unmap a previously mapped plane with gst_video_meta_map(). - - - TRUE if the memory was successfully unmapped. - - - - - a #GstVideoMeta - - - - a plane - - - - a #GstMapInfo - - - - - - - - - - - - - Extra data passed to a video transform #GstMetaTransformFunction such as: -"gst-video-scale". - - - the input #GstVideoInfo - - - - the output #GstVideoInfo - - - - Get the #GQuark for the "gst-video-scale" metadata transform operation. - - - a #GQuark - - - - - - GstVideoMultiviewFlags are used to indicate extra properties of a -stereo/multiview stream beyond the frame layout and buffer mapping -that is conveyed in the #GstVideoMultiviewMode. - - No flags - - - For stereo streams, the - normal arrangement of left and right views is reversed. - - - The left view is vertically - mirrored. - - - The left view is horizontally - mirrored. - - - The right view is - vertically mirrored. - - - The right view is - horizontally mirrored. - - - For frame-packed - multiview modes, indicates that the individual - views have been encoded with half the true width or height - and should be scaled back up for display. This flag - is used for overriding input layout interpretation - by adjusting pixel-aspect-ratio. - For side-by-side, column interleaved or checkerboard packings, the - pixel width will be doubled. For row interleaved and top-bottom - encodings, pixel height will be doubled. - - - The video stream contains both - mono and multiview portions, signalled on each buffer by the - absence or presence of the @GST_VIDEO_BUFFER_FLAG_MULTIPLE_VIEW - buffer flag. - - - - See #GstVideoMultiviewFlags. - - - #GstVideoMultiviewFramePacking represents the subset of #GstVideoMultiviewMode -values that can be applied to any video frame without needing extra metadata. -It can be used by elements that provide a property to override the -multiview interpretation of a video stream when the video doesn't contain -any markers. - -This enum is used (for example) on playbin, to re-interpret a played -video stream as a stereoscopic video. The individual enum values are -equivalent to and have the same value as the matching #GstVideoMultiviewMode. - - A special value indicating -no frame packing info. - - - All frames are monoscopic. - - - All frames represent a left-eye view. - - - All frames represent a right-eye view. - - - Left and right eye views are -provided in the left and right half of the frame respectively. - - - Left and right eye -views are provided in the left and right half of the frame, but -have been sampled using quincunx method, with half-pixel offset -between the 2 views. - - - Alternating vertical -columns of pixels represent the left and right eye view respectively. - - - Alternating horizontal -rows of pixels represent the left and right eye view respectively. - - - The top half of the frame -contains the left eye, and the bottom half the right eye. - - - Pixels are arranged with -alternating pixels representing left and right eye views in a -checkerboard fashion. - - - - All possible stereoscopic 3D and multiview representations. -In conjunction with #GstVideoMultiviewFlags, describes how -multiview content is being transported in the stream. - - A special value indicating -no multiview information. Used in GstVideoInfo and other places to -indicate that no specific multiview handling has been requested or -provided. This value is never carried on caps. - - - All frames are monoscopic. - - - All frames represent a left-eye view. - - - All frames represent a right-eye view. - - - Left and right eye views are -provided in the left and right half of the frame respectively. - - - Left and right eye -views are provided in the left and right half of the frame, but -have been sampled using quincunx method, with half-pixel offset -between the 2 views. - - - Alternating vertical -columns of pixels represent the left and right eye view respectively. - - - Alternating horizontal -rows of pixels represent the left and right eye view respectively. - - - The top half of the frame -contains the left eye, and the bottom half the right eye. - - - Pixels are arranged with -alternating pixels representing left and right eye views in a -checkerboard fashion. - - - Left and right eye views -are provided in separate frames alternately. - - - Multiple -independent views are provided in separate frames in sequence. -This method only applies to raw video buffers at the moment. -Specific view identification is via the `GstVideoMultiviewMeta` -and #GstVideoMeta(s) on raw video buffers. - - - Multiple views are -provided as separate #GstMemory framebuffers attached to each -#GstBuffer, described by the `GstVideoMultiviewMeta` -and #GstVideoMeta(s) - - - - - The #GstVideoMultiviewMode value - -Given a string from a caps multiview-mode field, -output the corresponding #GstVideoMultiviewMode -or #GST_VIDEO_MULTIVIEW_MODE_NONE - - - - - multiview-mode field string from caps - - - - - - - - The caps string representation of the mode, or NULL if invalid. - -Given a #GstVideoMultiviewMode returns the multiview-mode caps string -for insertion into a caps structure - - - - - A #GstVideoMultiviewMode value - - - - - - - The interface allows unified access to control flipping and autocenter -operation of video-sources or operators. - - - Get the horizontal centering offset from the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the horizontal flipping state (%TRUE for flipped) from the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the vertical centering offset from the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the vertical flipping state (%TRUE for flipped) from the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Set the horizontal centering offset for the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - Set the horizontal flipping state (%TRUE for flipped) for the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - Set the vertical centering offset for the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - Set the vertical flipping state (%TRUE for flipped) for the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - Get the horizontal centering offset from the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the horizontal flipping state (%TRUE for flipped) from the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the vertical centering offset from the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Get the vertical flipping state (%TRUE for flipped) from the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - Set the horizontal centering offset for the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - Set the horizontal flipping state (%TRUE for flipped) for the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - Set the vertical centering offset for the given object. - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - Set the vertical flipping state (%TRUE for flipped) for the given object. - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - - #GstVideoOrientationInterface interface. - - - parent interface type. - - - - - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - - - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - - - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - - - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - return location for the result - - - - - - - - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - - - - - %TRUE in case the element supports flipping - - - - - #GstVideoOrientation interface of a #GstElement - - - - use flipping - - - - - - - - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - - - - - %TRUE in case the element supports centering - - - - - #GstVideoOrientation interface of a #GstElement - - - - centering offset - - - - - - - - The different video orientation methods. - - Identity (no rotation) - - - Rotate clockwise 90 degrees - - - Rotate 180 degrees - - - Rotate counter-clockwise 90 degrees - - - Flip horizontally - - - Flip vertically - - - Flip across upper left/lower right diagonal - - - Flip across upper right/lower left diagonal - - - Select flip method based on image-orientation tag - - - Current status depends on plugin internal setup - - - - The #GstVideoOverlay interface is used for 2 main purposes : - -* To get a grab on the Window where the video sink element is going to render. - This is achieved by either being informed about the Window identifier that - the video sink element generated, or by forcing the video sink element to use - a specific Window identifier for rendering. -* To force a redrawing of the latest video frame the video sink element - displayed on the Window. Indeed if the #GstPipeline is in #GST_STATE_PAUSED - state, moving the Window around will damage its content. Application - developers will want to handle the Expose events themselves and force the - video sink element to refresh the Window's content. - -Using the Window created by the video sink is probably the simplest scenario, -in some cases, though, it might not be flexible enough for application -developers if they need to catch events such as mouse moves and button -clicks. - -Setting a specific Window identifier on the video sink element is the most -flexible solution but it has some issues. Indeed the application needs to set -its Window identifier at the right time to avoid internal Window creation -from the video sink element. To solve this issue a #GstMessage is posted on -the bus to inform the application that it should set the Window identifier -immediately. Here is an example on how to do that correctly: -|[ -static GstBusSyncReply -create_window (GstBus * bus, GstMessage * message, GstPipeline * pipeline) -{ - // ignore anything but 'prepare-window-handle' element messages - if (!gst_is_video_overlay_prepare_window_handle_message (message)) - return GST_BUS_PASS; - - win = XCreateSimpleWindow (disp, root, 0, 0, 320, 240, 0, 0, 0); - - XSetWindowBackgroundPixmap (disp, win, None); - - XMapRaised (disp, win); - - XSync (disp, FALSE); - - gst_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)), - win); - - gst_message_unref (message); - - return GST_BUS_DROP; -} -... -int -main (int argc, char **argv) -{ -... - bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_set_sync_handler (bus, (GstBusSyncHandler) create_window, pipeline, - NULL); -... -} -]| - -## Two basic usage scenarios - -There are two basic usage scenarios: in the simplest case, the application -uses #playbin or #playsink or knows exactly what particular element is used -for video output, which is usually the case when the application creates -the videosink to use (e.g. #xvimagesink, #ximagesink, etc.) itself; in this -case, the application can just create the videosink element, create and -realize the window to render the video on and then -call gst_video_overlay_set_window_handle() directly with the XID or native -window handle, before starting up the pipeline. -As #playbin and #playsink implement the video overlay interface and proxy -it transparently to the actual video sink even if it is created later, this -case also applies when using these elements. - -In the other and more common case, the application does not know in advance -what GStreamer video sink element will be used for video output. This is -usually the case when an element such as #autovideosink is used. -In this case, the video sink element itself is created -asynchronously from a GStreamer streaming thread some time after the -pipeline has been started up. When that happens, however, the video sink -will need to know right then whether to render onto an already existing -application window or whether to create its own window. This is when it -posts a prepare-window-handle message, and that is also why this message needs -to be handled in a sync bus handler which will be called from the streaming -thread directly (because the video sink will need an answer right then). - -As response to the prepare-window-handle element message in the bus sync -handler, the application may use gst_video_overlay_set_window_handle() to tell -the video sink to render onto an existing window surface. At this point the -application should already have obtained the window handle / XID, so it -just needs to set it. It is generally not advisable to call any GUI toolkit -functions or window system functions from the streaming thread in which the -prepare-window-handle message is handled, because most GUI toolkits and -windowing systems are not thread-safe at all and a lot of care would be -required to co-ordinate the toolkit and window system calls of the -different threads (Gtk+ users please note: prior to Gtk+ 2.18 -`GDK_WINDOW_XID` was just a simple structure access, so generally fine to do -within the bus sync handler; this macro was changed to a function call in -Gtk+ 2.18 and later, which is likely to cause problems when called from a -sync handler; see below for a better approach without `GDK_WINDOW_XID` -used in the callback). - -## GstVideoOverlay and Gtk+ - -|[ -#include &lt;gst/video/videooverlay.h&gt; -#include &lt;gtk/gtk.h&gt; -#ifdef GDK_WINDOWING_X11 -#include &lt;gdk/gdkx.h&gt; // for GDK_WINDOW_XID -#endif -#ifdef GDK_WINDOWING_WIN32 -#include &lt;gdk/gdkwin32.h&gt; // for GDK_WINDOW_HWND -#endif -... -static guintptr video_window_handle = 0; -... -static GstBusSyncReply -bus_sync_handler (GstBus * bus, GstMessage * message, gpointer user_data) -{ - // ignore anything but 'prepare-window-handle' element messages - if (!gst_is_video_overlay_prepare_window_handle_message (message)) - return GST_BUS_PASS; - - if (video_window_handle != 0) { - GstVideoOverlay *overlay; - - // GST_MESSAGE_SRC (message) will be the video sink element - overlay = GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)); - gst_video_overlay_set_window_handle (overlay, video_window_handle); - } else { - g_warning ("Should have obtained video_window_handle by now!"); - } - - gst_message_unref (message); - return GST_BUS_DROP; -} -... -static void -video_widget_realize_cb (GtkWidget * widget, gpointer data) -{ -#if GTK_CHECK_VERSION(2,18,0) - // Tell Gtk+/Gdk to create a native window for this widget instead of - // drawing onto the parent widget. - // This is here just for pedagogical purposes, GDK_WINDOW_XID will call - // it as well in newer Gtk versions - if (!gdk_window_ensure_native (widget->window)) - g_error ("Couldn't create native window needed for GstVideoOverlay!"); -#endif - -#ifdef GDK_WINDOWING_X11 - { - gulong xid = GDK_WINDOW_XID (gtk_widget_get_window (video_window)); - video_window_handle = xid; - } -#endif -#ifdef GDK_WINDOWING_WIN32 - { - HWND wnd = GDK_WINDOW_HWND (gtk_widget_get_window (video_window)); - video_window_handle = (guintptr) wnd; - } -#endif -} -... -int -main (int argc, char **argv) -{ - GtkWidget *video_window; - GtkWidget *app_window; - ... - app_window = gtk_window_new (GTK_WINDOW_TOPLEVEL); - ... - video_window = gtk_drawing_area_new (); - g_signal_connect (video_window, "realize", - G_CALLBACK (video_widget_realize_cb), NULL); - gtk_widget_set_double_buffered (video_window, FALSE); - ... - // usually the video_window will not be directly embedded into the - // application window like this, but there will be many other widgets - // and the video window will be embedded in one of them instead - gtk_container_add (GTK_CONTAINER (ap_window), video_window); - ... - // show the GUI - gtk_widget_show_all (app_window); - - // realize window now so that the video window gets created and we can - // obtain its XID/HWND before the pipeline is started up and the videosink - // asks for the XID/HWND of the window to render onto - gtk_widget_realize (video_window); - - // we should have the XID/HWND now - g_assert (video_window_handle != 0); - ... - // set up sync handler for setting the xid once the pipeline is started - bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_set_sync_handler (bus, (GstBusSyncHandler) bus_sync_handler, NULL, - NULL); - gst_object_unref (bus); - ... - gst_element_set_state (pipeline, GST_STATE_PLAYING); - ... -} -]| - -## GstVideoOverlay and Qt - -|[ -#include <glib.h>; -#include <gst/gst.h>; -#include <gst/video/videooverlay.h>; - -#include <QApplication>; -#include <QTimer>; -#include <QWidget>; - -int main(int argc, char *argv[]) -{ - if (!g_thread_supported ()) - g_thread_init (NULL); - - gst_init (&argc, &argv); - QApplication app(argc, argv); - app.connect(&app, SIGNAL(lastWindowClosed()), &app, SLOT(quit ())); - - // prepare the pipeline - - GstElement *pipeline = gst_pipeline_new ("xvoverlay"); - GstElement *src = gst_element_factory_make ("videotestsrc", NULL); - GstElement *sink = gst_element_factory_make ("xvimagesink", NULL); - gst_bin_add_many (GST_BIN (pipeline), src, sink, NULL); - gst_element_link (src, sink); - - // prepare the ui - - QWidget window; - window.resize(320, 240); - window.show(); - - WId xwinid = window.winId(); - gst_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (sink), xwinid); - - // run the pipeline - - GstStateChangeReturn sret = gst_element_set_state (pipeline, - GST_STATE_PLAYING); - if (sret == GST_STATE_CHANGE_FAILURE) { - gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (pipeline); - // Exit application - QTimer::singleShot(0, QApplication::activeWindow(), SLOT(quit())); - } - - int ret = app.exec(); - - window.hide(); - gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (pipeline); - - return ret; -} -]| - - - This helper shall be used by classes implementing the #GstVideoOverlay -interface that want the render rectangle to be controllable using -properties. This helper will install "render-rectangle" property into the -class. - - - - - - - The class on which the properties will be installed - - - - The first free property ID to use - - - - - - This helper shall be used by classes implementing the #GstVideoOverlay -interface that want the render rectangle to be controllable using -properties. This helper will parse and set the render rectangle calling -gst_video_overlay_set_render_rectangle(). - - - %TRUE if the @property_id matches the GstVideoOverlay property - - - - - The instance on which the property is set - - - - The highest property ID. - - - - The property ID - - - - The #GValue to be set - - - - - - Tell an overlay that it has been exposed. This will redraw the current frame -in the drawable even if the pipeline is PAUSED. - - - - - - - a #GstVideoOverlay to expose. - - - - - - Tell an overlay that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window system, -events are not propagated in the window hierarchy if a client is listening -for them. This method allows you to disable events handling completely -from the #GstVideoOverlay. - - - - - - - a #GstVideoOverlay to expose. - - - - a #gboolean indicating if events should be handled or not. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This will call the video overlay's set_window_handle method. You -should use this method to tell to an overlay to display video output to a -specific window (e.g. an XWindow on X11). Passing 0 as the @handle will -tell the overlay to stop using that window and create an internal one. - - - - - - - a #GstVideoOverlay to set the window on. - - - - a handle referencing the window. - - - - - - Tell an overlay that it has been exposed. This will redraw the current frame -in the drawable even if the pipeline is PAUSED. - - - - - - - a #GstVideoOverlay to expose. - - - - - - This will post a "have-window-handle" element message on the bus. - -This function should only be used by video overlay plugin developers. - - - - - - - a #GstVideoOverlay which got a window - - - - a platform-specific handle referencing the window - - - - - - Tell an overlay that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window system, -events are not propagated in the window hierarchy if a client is listening -for them. This method allows you to disable events handling completely -from the #GstVideoOverlay. - - - - - - - a #GstVideoOverlay to expose. - - - - a #gboolean indicating if events should be handled or not. - - - - - - This will post a "prepare-window-handle" element message on the bus -to give applications an opportunity to call -gst_video_overlay_set_window_handle() before a plugin creates its own -window. - -This function should only be used by video overlay plugin developers. - - - - - - - a #GstVideoOverlay which does not yet have an Window handle set - - - - - - Configure a subregion as a video target within the window set by -gst_video_overlay_set_window_handle(). If this is not used or not supported -the video will fill the area of the window set as the overlay to 100%. -By specifying the rectangle, the video can be overlayed to a specific region -of that window only. After setting the new rectangle one should call -gst_video_overlay_expose() to force a redraw. To unset the region pass -1 for -the @width and @height parameters. - -This method is needed for non fullscreen video overlay in UI toolkits that -do not support subwindows. - - - %FALSE if not supported by the sink. - - - - - a #GstVideoOverlay - - - - the horizontal offset of the render area inside the window - - - - the vertical offset of the render area inside the window - - - - the width of the render area inside the window - - - - the height of the render area inside the window - - - - - - This will call the video overlay's set_window_handle method. You -should use this method to tell to an overlay to display video output to a -specific window (e.g. an XWindow on X11). Passing 0 as the @handle will -tell the overlay to stop using that window and create an internal one. - - - - - - - a #GstVideoOverlay to set the window on. - - - - a handle referencing the window. - - - - - - - Functions to create and handle overlay compositions on video buffers. - -An overlay composition describes one or more overlay rectangles to be -blended on top of a video buffer. - -This API serves two main purposes: - -* it can be used to attach overlay information (subtitles or logos) - to non-raw video buffers such as GL/VAAPI/VDPAU surfaces. The actual - blending of the overlay can then be done by e.g. the video sink that - processes these non-raw buffers. - -* it can also be used to blend overlay rectangles on top of raw video - buffers, thus consolidating blending functionality for raw video in - one place. - -Together, this allows existing overlay elements to easily handle raw -and non-raw video as input in without major changes (once the overlays -have been put into a #GstVideoOverlayComposition object anyway) - for raw -video the overlay can just use the blending function to blend the data -on top of the video, and for surface buffers it can just attach them to -the buffer and let the sink render the overlays. - - - Creates a new video overlay composition object to hold one or more -overlay rectangles. - - - a new #GstVideoOverlayComposition. Unref with - gst_video_overlay_composition_unref() when no longer needed. - - - - - a #GstVideoOverlayRectangle to add to the - composition - - - - - - Adds an overlay rectangle to an existing overlay composition object. This -must be done right after creating the overlay composition. - - - - - - - a #GstVideoOverlayComposition - - - - a #GstVideoOverlayRectangle to add to the - composition - - - - - - Blends the overlay rectangles in @comp on top of the raw video data -contained in @video_buf. The data in @video_buf must be writable and -mapped appropriately. - -Since @video_buf data is read and will be modified, it ought be -mapped with flag GST_MAP_READWRITE. - - - - - - - a #GstVideoOverlayComposition - - - - a #GstVideoFrame containing raw video data in a - supported format. It should be mapped using GST_MAP_READWRITE - - - - - - Makes a copy of @comp and all contained rectangles, so that it is possible -to modify the composition and contained rectangles (e.g. add additional -rectangles or change the render co-ordinates or render dimension). The -actual overlay pixel data buffers contained in the rectangles are not -copied. - - - a new #GstVideoOverlayComposition equivalent - to @comp. - - - - - a #GstVideoOverlayComposition to copy - - - - - - Returns the @n-th #GstVideoOverlayRectangle contained in @comp. - - - the @n-th rectangle, or NULL if @n is out of - bounds. Will not return a new reference, the caller will need to - obtain her own reference using gst_video_overlay_rectangle_ref() - if needed. - - - - - a #GstVideoOverlayComposition - - - - number of the rectangle to get - - - - - - Returns the sequence number of this composition. Sequence numbers are -monotonically increasing and unique for overlay compositions and rectangles -(meaning there will never be a rectangle with the same sequence number as -a composition). - - - the sequence number of @comp - - - - - a #GstVideoOverlayComposition - - - - - - Takes ownership of @comp and returns a version of @comp that is writable -(i.e. can be modified). Will either return @comp right away, or create a -new writable copy of @comp and unref @comp itself. All the contained -rectangles will also be copied, but the actual overlay pixel data buffers -contained in the rectangles are not copied. - - - a writable #GstVideoOverlayComposition - equivalent to @comp. - - - - - a #GstVideoOverlayComposition to copy - - - - - - Returns the number of #GstVideoOverlayRectangle<!-- -->s contained in @comp. - - - the number of rectangles - - - - - a #GstVideoOverlayComposition - - - - - - - Extra buffer metadata describing image overlay data. - - - parent #GstMeta - - - - the attached #GstVideoOverlayComposition - - - - - - - - - - - Overlay format flags. - - no flags - - - RGB are premultiplied by A/255. - - - a global-alpha value != 1 is set. - - - - #GstVideoOverlay interface - - - parent interface type. - - - - - - - - - - - a #GstVideoOverlay to expose. - - - - - - - - - - - - - - a #GstVideoOverlay to expose. - - - - a #gboolean indicating if events should be handled or not. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GstVideoOverlay to set the window on. - - - - a handle referencing the window. - - - - - - - - An opaque video overlay rectangle object. A rectangle contains a single -overlay rectangle which can be added to a composition. - - - Creates a new video overlay rectangle with ARGB or AYUV pixel data. -The layout in case of ARGB of the components in memory is B-G-R-A -on little-endian platforms -(corresponding to #GST_VIDEO_FORMAT_BGRA) and A-R-G-B on big-endian -platforms (corresponding to #GST_VIDEO_FORMAT_ARGB). In other words, -pixels are treated as 32-bit words and the lowest 8 bits then contain -the blue component value and the highest 8 bits contain the alpha -component value. Unless specified in the flags, the RGB values are -non-premultiplied. This is the format that is used by most hardware, -and also many rendering libraries such as Cairo, for example. -The pixel data buffer must have #GstVideoMeta set. - - - a new #GstVideoOverlayRectangle. Unref with - gst_video_overlay_rectangle_unref() when no longer needed. - - - - - a #GstBuffer pointing to the pixel memory - - - - the X co-ordinate on the video where the top-left corner of this - overlay rectangle should be rendered to - - - - the Y co-ordinate on the video where the top-left corner of this - overlay rectangle should be rendered to - - - - the render width of this rectangle on the video - - - - the render height of this rectangle on the video - - - - flags - - - - - - Makes a copy of @rectangle, so that it is possible to modify it -(e.g. to change the render co-ordinates or render dimension). The -actual overlay pixel data buffers contained in the rectangle are not -copied. - - - a new #GstVideoOverlayRectangle equivalent - to @rectangle. - - - - - a #GstVideoOverlayRectangle to copy - - - - - - Retrieves the flags associated with a #GstVideoOverlayRectangle. -This is useful if the caller can handle both premultiplied alpha and -non premultiplied alpha, for example. By knowing whether the rectangle -uses premultiplied or not, it can request the pixel data in the format -it is stored in, to avoid unnecessary conversion. - - - the #GstVideoOverlayFormatFlags associated with the rectangle. - - - - - a #GstVideoOverlayRectangle - - - - - - Retrieves the global-alpha value associated with a #GstVideoOverlayRectangle. - - - the global-alpha value associated with the rectangle. - - - - - a #GstVideoOverlayRectangle - - - - - - - - a #GstBuffer holding the ARGB pixel data with - width and height of the render dimensions as per - gst_video_overlay_rectangle_get_render_rectangle(). This function does - not return a reference, the caller should obtain a reference of her own - with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - - - a #GstBuffer holding the AYUV pixel data with - width and height of the render dimensions as per - gst_video_overlay_rectangle_get_render_rectangle(). This function does - not return a reference, the caller should obtain a reference of her own - with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - - - a #GstBuffer holding the pixel data with - format as originally provided and specified in video meta with - width and height of the render dimensions as per - gst_video_overlay_rectangle_get_render_rectangle(). This function does - not return a reference, the caller should obtain a reference of her own - with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - Retrieves the pixel data as it is. This is useful if the caller can -do the scaling itself when handling the overlaying. The rectangle will -need to be scaled to the render dimensions, which can be retrieved using -gst_video_overlay_rectangle_get_render_rectangle(). - - - a #GstBuffer holding the ARGB pixel data with - #GstVideoMeta set. This function does not return a reference, the caller - should obtain a reference of her own with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags. - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - Retrieves the pixel data as it is. This is useful if the caller can -do the scaling itself when handling the overlaying. The rectangle will -need to be scaled to the render dimensions, which can be retrieved using -gst_video_overlay_rectangle_get_render_rectangle(). - - - a #GstBuffer holding the AYUV pixel data with - #GstVideoMeta set. This function does not return a reference, the caller - should obtain a reference of her own with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags. - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - Retrieves the pixel data as it is. This is useful if the caller can -do the scaling itself when handling the overlaying. The rectangle will -need to be scaled to the render dimensions, which can be retrieved using -gst_video_overlay_rectangle_get_render_rectangle(). - - - a #GstBuffer holding the pixel data with - #GstVideoMeta set. This function does not return a reference, the caller - should obtain a reference of her own with gst_buffer_ref() if needed. - - - - - a #GstVideoOverlayRectangle - - - - flags. - If a global_alpha value != 1 is set for the rectangle, the caller - should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag - if he wants to apply global-alpha himself. If the flag is not set - global_alpha is applied internally before returning the pixel-data. - - - - - - Retrieves the render position and render dimension of the overlay -rectangle on the video. - - - TRUE if valid render dimensions were retrieved. - - - - - a #GstVideoOverlayRectangle - - - - address where to store the X render offset - - - - address where to store the Y render offset - - - - address where to store the render width - - - - address where to store the render height - - - - - - Returns the sequence number of this rectangle. Sequence numbers are -monotonically increasing and unique for overlay compositions and rectangles -(meaning there will never be a rectangle with the same sequence number as -a composition). - -Using the sequence number of a rectangle as an indicator for changed -pixel-data of a rectangle is dangereous. Some API calls, like e.g. -gst_video_overlay_rectangle_set_global_alpha(), automatically update -the per rectangle sequence number, which is misleading for renderers/ -consumers, that handle global-alpha themselves. For them the -pixel-data returned by gst_video_overlay_rectangle_get_pixels_*() -won't be different for different global-alpha values. In this case a -renderer could also use the GstBuffer pointers as a hint for changed -pixel-data. - - - the sequence number of @rectangle - - - - - a #GstVideoOverlayRectangle - - - - - - Sets the global alpha value associated with a #GstVideoOverlayRectangle. Per- -pixel alpha values are multiplied with this value. Valid -values: 0 <= global_alpha <= 1; 1 to deactivate. - -@rectangle must be writable, meaning its refcount must be 1. You can -make the rectangles inside a #GstVideoOverlayComposition writable using -gst_video_overlay_composition_make_writable() or -gst_video_overlay_composition_copy(). - - - - - - - a #GstVideoOverlayRectangle - - - - Global alpha value (0 to 1.0) - - - - - - Sets the render position and dimensions of the rectangle on the video. -This function is mainly for elements that modify the size of the video -in some way (e.g. through scaling or cropping) and need to adjust the -details of any overlays to match the operation that changed the size. - -@rectangle must be writable, meaning its refcount must be 1. You can -make the rectangles inside a #GstVideoOverlayComposition writable using -gst_video_overlay_composition_make_writable() or -gst_video_overlay_composition_copy(). - - - - - - - a #GstVideoOverlayRectangle - - - - render X position of rectangle on video - - - - render Y position of rectangle on video - - - - render width of rectangle - - - - render height of rectangle - - - - - - - The different flags that can be used when packing and unpacking. - - No flag - - - When the source has a smaller depth - than the target format, set the least significant bits of the target - to 0. This is likely slightly faster but less accurate. When this flag - is not specified, the most significant bits of the source are duplicated - in the least significant bits of the destination. - - - The source is interlaced. The unpacked - format will be interlaced as well with each line containing - information from alternating fields. (Since: 1.2) - - - - Different primaries conversion modes - - disable conversion between primaries - - - do conversion between primaries only - when it can be merged with color matrix conversion. - - - fast conversion between primaries - - - - Helper structure representing a rectangular area. - - - X coordinate of rectangle's top-left point - - - - Y coordinate of rectangle's top-left point - - - - width of the rectangle - - - - height of the rectangle - - - - - Extra buffer metadata describing an image region of interest - - - parent #GstMeta - - - - GQuark describing the semantic of the Roi (f.i. a face, a pedestrian) - - - - identifier of this particular ROI - - - - identifier of its parent ROI, used f.i. for ROI hierarchisation. - - - - x component of upper-left corner - - - - y component of upper-left corner - - - - bounding box width - - - - bounding box height - - - - list of #GstStructure containing element-specific params for downstream, - see gst_video_region_of_interest_meta_add_param(). (Since: 1.14) - - - - - - Attach element-specific parameters to @meta meant to be used by downstream -elements which may handle this ROI. -The name of @s is used to identify the element these parameters are meant for. - -This is typically used to tell encoders how they should encode this specific region. -For example, a structure named "roi/x264enc" could be used to give the -QP offsets this encoder should use when encoding the region described in @meta. -Multiple parameters can be defined for the same meta so different encoders -can be supported by cross platform applications). - - - - - - - a #GstVideoRegionOfInterestMeta - - - - a #GstStructure - - - - - - Retrieve the parameter for @meta having @name as structure name, -or %NULL if there is none. - -See also: gst_video_region_of_interest_meta_add_param() - - - a #GstStructure - - - - - a #GstVideoRegionOfInterestMeta - - - - a name. - - - - - - - - - - - - - #GstVideoResampler is a structure which holds the information -required to perform various kinds of resampling filtering. - - - the input size - - - - the output size - - - - the maximum number of taps - - - - the number of phases - - - - array with the source offset for each output element - - - - array with the phase to use for each output element - - - - array with new number of taps for each phase - - - - the taps for all phases - - - - - - - - - Clear a previously initialized #GstVideoResampler @resampler. - - - - - - - a #GstVideoResampler - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Different resampler flags. - - no flags - - - when no taps are given, half the - number of calculated taps. This can be used when making scalers - for the different fields of an interlaced picture. Since: 1.10 - - - - Different subsampling and upsampling methods - - Duplicates the samples when - upsampling and drops when downsampling - - - Uses linear interpolation to reconstruct - missing samples and averaging to downsample - - - Uses cubic interpolation - - - Uses sinc interpolation - - - Uses lanczos interpolation - - - - #GstVideoScaler is a utility object for rescaling and resampling -video frames using various interpolation / sampling methods. - - - Scale a rectangle of pixels in @src with @src_stride to @dest with -@dest_stride using the horizontal scaler @hscaler and the vertical -scaler @vscale. - -One or both of @hscale and @vscale can be NULL to only perform scaling in -one dimension or do a copy without scaling. - -@x and @y are the coordinates in the destination image to process. - - - - - - - a horizontal #GstVideoScaler - - - - a vertical #GstVideoScaler - - - - a #GstVideoFormat for @srcs and @dest - - - - source pixels - - - - source pixels stride - - - - destination pixels - - - - destination pixels stride - - - - the horizontal destination offset - - - - the vertical destination offset - - - - the number of output pixels to scale - - - - the number of output lines to scale - - - - - - Combine a scaler for Y and UV into one scaler for the packed @format. - - - a new horizontal videoscaler for @format. - - - - - a scaler for the Y component - - - - a scaler for the U and V components - - - - the input video format - - - - the output video format - - - - - - Free a previously allocated #GstVideoScaler @scale. - - - - - - - a #GstVideoScaler - - - - - - For a given pixel at @out_offset, get the first required input pixel at -@in_offset and the @n_taps filter coefficients. - -Note that for interlaced content, @in_offset needs to be incremented with -2 to get the next input line. - - - an array of @n_tap gdouble values with filter coefficients. - - - - - a #GstVideoScaler - - - - an output offset - - - - result input offset - - - - result n_taps - - - - - - Get the maximum number of taps for @scale. - - - the maximum number of taps - - - - - a #GstVideoScaler - - - - - - Horizontally scale the pixels in @src to @dest, starting from @dest_offset -for @width samples. - - - - - - - a #GstVideoScaler - - - - a #GstVideoFormat for @src and @dest - - - - source pixels - - - - destination pixels - - - - the horizontal destination offset - - - - the number of pixels to scale - - - - - - Vertically combine @width pixels in the lines in @src_lines to @dest. -@dest is the location of the target line at @dest_offset and -@srcs are the input lines for @dest_offset. - - - - - - - a #GstVideoScaler - - - - a #GstVideoFormat for @srcs and @dest - - - - source pixels lines - - - - destination pixels - - - - the vertical destination offset - - - - the number of pixels to scale - - - - - - Make a new @method video scaler. @in_size source lines/pixels will -be scaled to @out_size destination lines/pixels. - -@n_taps specifies the amount of pixels to use from the source for one output -pixel. If n_taps is 0, this function chooses a good value automatically based -on the @method and @in_size/@out_size. - - - a #GstVideoScaler - - - - - a #GstVideoResamplerMethod - - - - #GstVideoScalerFlags - - - - number of taps to use - - - - number of source elements - - - - number of destination elements - - - - extra options - - - - - - - Different scale flags. - - no flags - - - Set up a scaler for interlaced content - - - - Provides useful functions and a base class for video sinks. - -GstVideoSink will configure the default base sink to drop frames that -arrive later than 20ms as this is considered the default threshold for -observing out-of-sync frames. - - - Takes @src rectangle and position it at the center of @dst rectangle with or -without @scaling. It handles clipping if the @src rectangle is bigger than -the @dst one and @scaling is set to FALSE. - - - - - - - the #GstVideoRectangle describing the source area - - - - the #GstVideoRectangle describing the destination area - - - - a pointer to a #GstVideoRectangle which will receive the result area - - - - a #gboolean indicating if scaling should be applied or not - - - - - - - - - - - - - - - - - - - - Whether to show video frames during preroll. If set to %FALSE, video -frames will only be rendered in PLAYING state. - - - - - - - video width (derived class needs to set this) - - - - video height (derived class needs to set this) - - - - - - - - - - - - - The video sink class structure. Derived classes should override the -@show_frame virtual function. - - - the parent class structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Enum value describing the available tiling modes. - - Unknown or unset tile mode - - - Every four adjacent blocks - two - horizontally and two vertically are grouped together and are located - in memory in Z or flipped Z order. In case of odd rows, the last row - of blocks is arranged in linear order. - - - Tiles are in row order. (Since: 1.18) - - - - Enum value describing the most common tiling types. - - Tiles are indexed. Use - gst_video_tile_get_index () to retrieve the tile at the requested - coordinates. - - - - @field_count must be 0 for progressive video and 1 or 2 for interlaced. - -A representation of a SMPTE time code. - -@hours must be positive and less than 24. Will wrap around otherwise. -@minutes and @seconds must be positive and less than 60. -@frames must be less than or equal to @config.fps_n / @config.fps_d -These values are *NOT* automatically normalized. - - - the corresponding #GstVideoTimeCodeConfig - - - - the hours field of #GstVideoTimeCode - - - - the minutes field of #GstVideoTimeCode - - - - the seconds field of #GstVideoTimeCode - - - - the frames field of #GstVideoTimeCode - - - - Interlaced video field count - - - - @field_count is 0 for progressive, 1 or 2 for interlaced. -@latest_daiy_jam reference is stolen from caller. - - - a new #GstVideoTimeCode with the given values. -The values are not checked for being in a valid range. To see if your -timecode actually has valid content, use gst_video_time_code_is_valid(). - - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - The latest daily jam of the #GstVideoTimeCode - - - - #GstVideoTimeCodeFlags - - - - the hours field of #GstVideoTimeCode - - - - the minutes field of #GstVideoTimeCode - - - - the seconds field of #GstVideoTimeCode - - - - the frames field of #GstVideoTimeCode - - - - Interlaced video field count - - - - - - - - a new empty, invalid #GstVideoTimeCode - - - - - The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - -This might return a completely invalid timecode, use -gst_video_time_code_new_from_date_time_full() to ensure -that you would get %NULL instead in that case. - - - the #GstVideoTimeCode representation of @dt. - - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - #GDateTime to convert - - - - #GstVideoTimeCodeFlags - - - - Interlaced video field count - - - - - - The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - - - the #GstVideoTimeCode representation of @dt, or %NULL if - no valid timecode could be created. - - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - #GDateTime to convert - - - - #GstVideoTimeCodeFlags - - - - Interlaced video field count - - - - - - - - a new #GstVideoTimeCode from the given string or %NULL - if the string could not be passed. - - - - - The string that represents the #GstVideoTimeCode - - - - - - Adds or subtracts @frames amount of frames to @tc. tc needs to -contain valid data, as verified by gst_video_time_code_is_valid(). - - - - - - - a valid #GstVideoTimeCode - - - - How many frames to add or subtract - - - - - - This makes a component-wise addition of @tc_inter to @tc. For example, -adding ("01:02:03:04", "00:01:00:00") will return "01:03:03:04". -When it comes to drop-frame timecodes, -adding ("00:00:00;00", "00:01:00:00") will return "00:01:00;02" -because of drop-frame oddities. However, -adding ("00:09:00;02", "00:01:00:00") will return "00:10:00;00" -because this time we can have an exact minute. - - - A new #GstVideoTimeCode with @tc_inter added or %NULL - if the interval can't be added. - - - - - The #GstVideoTimeCode where the diff should be added. This -must contain valid timecode values. - - - - The #GstVideoTimeCodeInterval to add to @tc. -The interval must contain valid values, except that for drop-frame -timecode, it may also contain timecodes which would normally -be dropped. These are then corrected to the next reasonable timecode. - - - - - - Initializes @tc with empty/zero/NULL values and frees any memory -it might currently use. - - - - - - - a #GstVideoTimeCode - - - - - - Compares @tc1 and @tc2. If both have latest daily jam information, it is -taken into account. Otherwise, it is assumed that the daily jam of both -@tc1 and @tc2 was at the same time. Both time codes must be valid. - - - 1 if @tc1 is after @tc2, -1 if @tc1 is before @tc2, 0 otherwise. - - - - - a valid #GstVideoTimeCode - - - - another valid #GstVideoTimeCode - - - - - - - - a new #GstVideoTimeCode with the same values as @tc. - - - - - a #GstVideoTimeCode - - - - - - - - how many frames have passed since the daily jam of @tc. - - - - - a valid #GstVideoTimeCode - - - - - - Frees @tc. - - - - - - - a #GstVideoTimeCode - - - - - - Adds one frame to @tc. - - - - - - - a valid #GstVideoTimeCode - - - - - - @field_count is 0 for progressive, 1 or 2 for interlaced. -@latest_daiy_jam reference is stolen from caller. - -Initializes @tc with the given values. -The values are not checked for being in a valid range. To see if your -timecode actually has valid content, use gst_video_time_code_is_valid(). - - - - - - - a #GstVideoTimeCode - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - The latest daily jam of the #GstVideoTimeCode - - - - #GstVideoTimeCodeFlags - - - - the hours field of #GstVideoTimeCode - - - - the minutes field of #GstVideoTimeCode - - - - the seconds field of #GstVideoTimeCode - - - - the frames field of #GstVideoTimeCode - - - - Interlaced video field count - - - - - - The resulting config->latest_daily_jam is set to midnight, and timecode is -set to the given time. - -Will assert on invalid parameters, use gst_video_time_code_init_from_date_time_full() -for being able to handle invalid parameters. - - - - - - - an uninitialized #GstVideoTimeCode - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - #GDateTime to convert - - - - #GstVideoTimeCodeFlags - - - - Interlaced video field count - - - - - - The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - - - %TRUE if @tc could be correctly initialized to a valid timecode - - - - - a #GstVideoTimeCode - - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - #GDateTime to convert - - - - #GstVideoTimeCodeFlags - - - - Interlaced video field count - - - - - - - - whether @tc is a valid timecode (supported frame rate, -hours/minutes/seconds/frames not overflowing) - - - - - #GstVideoTimeCode to check - - - - - - - - how many nsec have passed since the daily jam of @tc. - - - - - a valid #GstVideoTimeCode - - - - - - The @tc.config->latest_daily_jam is required to be non-NULL. - - - the #GDateTime representation of @tc or %NULL if @tc - has no daily jam. - - - - - A valid #GstVideoTimeCode to convert - - - - - - - - the SMPTE ST 2059-1:2015 string representation of @tc. That will -take the form hh:mm:ss:ff. The last separator (between seconds and frames) -may vary: - -';' for drop-frame, non-interlaced content and for drop-frame interlaced -field 2 -',' for drop-frame interlaced field 1 -':' for non-drop-frame, non-interlaced content and for non-drop-frame -interlaced field 2 -'.' for non-drop-frame interlaced field 1 - - - - - A #GstVideoTimeCode to convert - - - - - - - Supported frame rates: 30000/1001, 60000/1001 (both with and without drop -frame), and integer frame rates e.g. 25/1, 30/1, 50/1, 60/1. - -The configuration of the time code. - - - Numerator of the frame rate - - - - Denominator of the frame rate - - - - the corresponding #GstVideoTimeCodeFlags - - - - The latest daily jam information, if present, or NULL - - - - - Flags related to the time code information. -For drop frame, only 30000/1001 and 60000/1001 frame rates are supported. - - No flags - - - Whether we have drop frame rate - - - Whether we have interlaced video - - - - A representation of a difference between two #GstVideoTimeCode instances. -Will not necessarily correspond to a real timecode (e.g. 00:00:10;00) - - - the hours field of #GstVideoTimeCodeInterval - - - - the minutes field of #GstVideoTimeCodeInterval - - - - the seconds field of #GstVideoTimeCodeInterval - - - - the frames field of #GstVideoTimeCodeInterval - - - - - - a new #GstVideoTimeCodeInterval with the given values. - - - - - the hours field of #GstVideoTimeCodeInterval - - - - the minutes field of #GstVideoTimeCodeInterval - - - - the seconds field of #GstVideoTimeCodeInterval - - - - the frames field of #GstVideoTimeCodeInterval - - - - - - @tc_inter_str must only have ":" as separators. - - - a new #GstVideoTimeCodeInterval from the given string - or %NULL if the string could not be passed. - - - - - The string that represents the #GstVideoTimeCodeInterval - - - - - - Initializes @tc with empty/zero/NULL values. - - - - - - - a #GstVideoTimeCodeInterval - - - - - - - - a new #GstVideoTimeCodeInterval with the same values as @tc. - - - - - a #GstVideoTimeCodeInterval - - - - - - Frees @tc. - - - - - - - a #GstVideoTimeCodeInterval - - - - - - Initializes @tc with the given values. - - - - - - - a #GstVideoTimeCodeInterval - - - - the hours field of #GstVideoTimeCodeInterval - - - - the minutes field of #GstVideoTimeCodeInterval - - - - the seconds field of #GstVideoTimeCodeInterval - - - - the frames field of #GstVideoTimeCodeInterval - - - - - - - Extra buffer metadata describing the GstVideoTimeCode of the frame. - -Each frame is assumed to have its own timecode, i.e. they are not -automatically incremented/interpolated. - - - parent #GstMeta - - - - the GstVideoTimeCode to attach - - - - - - - - - - - The video transfer function defines the formula for converting between -non-linear RGB (R'G'B') and linear RGB - - unknown transfer function - - - linear RGB, gamma 1.0 curve - - - Gamma 1.8 curve - - - Gamma 2.0 curve - - - Gamma 2.2 curve - - - Gamma 2.2 curve with a linear segment in the lower - range, also ITU-R BT470M / ITU-R BT1700 625 PAL & - SECAM / ITU-R BT1361 - - - Gamma 2.2 curve with a linear segment in the - lower range - - - Gamma 2.4 curve with a linear segment in the lower - range. IEC 61966-2-1 (sRGB or sYCC) - - - Gamma 2.8 curve, also ITU-R BT470BG - - - Logarithmic transfer characteristic - 100:1 range - - - Logarithmic transfer characteristic - 316.22777:1 range (100 * sqrt(10) : 1) - - - Gamma 2.2 curve with a linear segment in the lower - range. Used for BT.2020 with 12 bits per - component. Since: 1.6 - - - Gamma 2.19921875. Since: 1.8 - - - Rec. ITU-R BT.2020-2 with 10 bits per component. - (functionally the same as the values - GST_VIDEO_TRANSFER_BT709 and GST_VIDEO_TRANSFER_BT601). - Since: 1.18 - - - SMPTE ST 2084 for 10, 12, 14, and 16-bit systems. - Known as perceptual quantization (PQ) - Since: 1.18 - - - Association of Radio Industries and Businesses (ARIB) - STD-B67 and Rec. ITU-R BT.2100-1 hybrid loggamma (HLG) system - Since: 1.18 - - - also known as SMPTE170M / ITU-R BT1358 525 or 625 / ITU-R BT1700 NTSC - Functionally the same as the values - GST_VIDEO_TRANSFER_BT709, and GST_VIDEO_TRANSFER_BT2020_10. - Since: 1.18 - - - Converts the @value to the #GstVideoTransferFunction -The transfer characteristics (TransferCharacteristics) value is -defined by "ISO/IEC 23001-8 Section 7.2 Table 3" -and "ITU-T H.273 Table 3". -"H.264 Table E-4" and "H.265 Table E.4" share the identical values. - - - the matched #GstVideoTransferFunction - - - - - a ITU-T H.273 transfer characteristics value - - - - - - Returns whether @from_func and @to_func are equivalent. There are cases -(e.g. BT601, BT709, and BT2020_10) where several functions are functionally -identical. In these cases, when doing conversion, we should consider them -as equivalent. Also, BT2020_12 is the same as the aforementioned three for -less than 12 bits per pixel. - - - TRUE if @from_func and @to_func can be considered equivalent. - - - - - #GstVideoTransferFunction to convert from - - - - bits per pixel to convert from - - - - #GstVideoTransferFunction to convert into - - - - bits per pixel to convert into - - - - - - Converts #GstVideoTransferFunction to the "transfer characteristics" -(TransferCharacteristics) value defined by "ISO/IEC 23001-8 Section 7.2 Table 3" -and "ITU-T H.273 Table 3". -"H.264 Table E-4" and "H.265 Table E.4" share the identical values. - - - The value of ISO/IEC 23001-8 transfer characteristics. - - - - - a #GstVideoTransferFunction - - - - - - - An encoder for writing ancillary data to the -Vertical Blanking Interval lines of component signals. - - - Create a new #GstVideoVBIEncoder for the specified @format and @pixel_width. - - - The new #GstVideoVBIEncoder or %NULL if the @format and/or @pixel_width -is not supported. - - - - - a #GstVideoFormat - - - - The width in pixel to use - - - - - - Stores Video Ancillary data, according to SMPTE-291M specification. - -Note that the contents of the data are always read as 8bit data (i.e. do not contain -the parity check bits). - - - %TRUE if enough space was left in the current line, %FALSE - otherwise. - - - - - a #GstVideoVBIEncoder - - - - %TRUE if composite ADF should be created, component otherwise - - - - The Data Identifier - - - - The Secondary Data Identifier (if type 2) or the Data - Block Number (if type 1) - - - - The user data content of the Ancillary packet. - Does not contain the ADF, DID, SDID nor CS. - - - - - - The amount of data (in bytes) in @data (max 255 bytes) - - - - - - - - - - - - - - - - - Frees the @encoder. - - - - - - - a #GstVideoVBIEncoder - - - - - - - - - - - - - - - - - - - - - A parser for detecting and extracting @GstVideoAncillary data from -Vertical Blanking Interval lines of component signals. - - - Create a new #GstVideoVBIParser for the specified @format and @pixel_width. - - - The new #GstVideoVBIParser or %NULL if the @format and/or @pixel_width -is not supported. - - - - - a #GstVideoFormat - - - - The width in pixel to use - - - - - - Provide a new line of data to the @parser. Call gst_video_vbi_parser_get_ancillary() -to get the Ancillary data that might be present on that line. - - - - - - - a #GstVideoVBIParser - - - - The line of data to parse - - - - - - - - - - - - - - - - - - - Frees the @parser. - - - - - - - a #GstVideoVBIParser - - - - - - Parse the line provided previously by gst_video_vbi_parser_add_line(). - - - %GST_VIDEO_VBI_PARSER_RESULT_OK if ancillary data was found and -@anc was filled. %GST_VIDEO_VBI_PARSER_RESULT_DONE if there wasn't any -data. - - - - - a #GstVideoVBIParser - - - - a #GstVideoAncillary to start the eventual ancillary data - - - - - - - Return values for #GstVideoVBIParser - - No line were provided, or no more Ancillary data was found. - - - A #GstVideoAncillary was found. - - - An error occurred - - - - Attaches #GstVideoAFDMeta metadata to @buffer with the given -parameters. - - - the #GstVideoAFDMeta on @buffer. - - - - - a #GstBuffer - - - - 0 for progressive or field 1 and 1 for field 2 - - - - #GstVideoAFDSpec that applies to AFD value - - - - #GstVideoAFDValue AFD enumeration - - - - - - Attaches GstVideoAffineTransformationMeta metadata to @buffer with -the given parameters. - - - the #GstVideoAffineTransformationMeta on @buffer. - - - - - a #GstBuffer - - - - - - Attaches #GstVideoBarMeta metadata to @buffer with the given -parameters. - - - the #GstVideoBarMeta on @buffer. - -See Table 6.11 Bar Data Syntax - -https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf - - - - - a #GstBuffer - - - - 0 for progressive or field 1 and 1 for field 2 - - - - if true then bar data specifies letterbox, otherwise pillarbox - - - - If @is_letterbox is true, then the value specifies the - last line of a horizontal letterbox bar area at top of reconstructed frame. - Otherwise, it specifies the last horizontal luminance sample of a vertical pillarbox - bar area at the left side of the reconstructed frame - - - - If @is_letterbox is true, then the value specifies the - first line of a horizontal letterbox bar area at bottom of reconstructed frame. - Otherwise, it specifies the first horizontal - luminance sample of a vertical pillarbox bar area at the right side of the reconstructed frame. - - - - - - Attaches #GstVideoCaptionMeta metadata to @buffer with the given -parameters. - - - the #GstVideoCaptionMeta on @buffer. - - - - - a #GstBuffer - - - - The type of Closed Caption to add - - - - The Closed Caption data - - - - - - The size of @data in bytes - - - - - - - - - - - - - Attaches GstVideoGLTextureUploadMeta metadata to @buffer with the given -parameters. - - - the #GstVideoGLTextureUploadMeta on @buffer. - - - - - a #GstBuffer - - - - the #GstVideoGLTextureOrientation - - - - the number of textures - - - - array of #GstVideoGLTextureType - - - - the function to upload the buffer to a specific texture ID - - - - user data for the implementor of @upload - - - - function to copy @user_data - - - - function to free @user_data - - - - - - Attaches GstVideoMeta metadata to @buffer with the given parameters and the -default offsets and strides for @format and @width x @height. - -This function calculates the default offsets and strides and then calls -gst_buffer_add_video_meta_full() with them. - - - the #GstVideoMeta on @buffer. - - - - - a #GstBuffer - - - - #GstVideoFrameFlags - - - - a #GstVideoFormat - - - - the width - - - - the height - - - - - - Attaches GstVideoMeta metadata to @buffer with the given parameters. - - - the #GstVideoMeta on @buffer. - - - - - a #GstBuffer - - - - #GstVideoFrameFlags - - - - a #GstVideoFormat - - - - the width - - - - the height - - - - number of planes - - - - offset of each plane - - - - - - stride of each plane - - - - - - - - Sets an overlay composition on a buffer. The buffer will obtain its own -reference to the composition, meaning this function does not take ownership -of @comp. - - - a #GstVideoOverlayCompositionMeta - - - - - a #GstBuffer - - - - a #GstVideoOverlayComposition - - - - - - Attaches #GstVideoRegionOfInterestMeta metadata to @buffer with the given -parameters. - - - the #GstVideoRegionOfInterestMeta on @buffer. - - - - - a #GstBuffer - - - - Type of the region of interest (e.g. "face") - - - - X position - - - - Y position - - - - width - - - - height - - - - - - Attaches #GstVideoRegionOfInterestMeta metadata to @buffer with the given -parameters. - - - the #GstVideoRegionOfInterestMeta on @buffer. - - - - - a #GstBuffer - - - - Type of the region of interest (e.g. "face") - - - - X position - - - - Y position - - - - width - - - - height - - - - - - Attaches #GstVideoTimeCodeMeta metadata to @buffer with the given -parameters. - - - the #GstVideoTimeCodeMeta on @buffer, or -(since 1.16) %NULL if the timecode was invalid. - - - - - a #GstBuffer - - - - a #GstVideoTimeCode - - - - - - Attaches #GstVideoTimeCodeMeta metadata to @buffer with the given -parameters. - - - the #GstVideoTimeCodeMeta on @buffer, or -(since 1.16) %NULL if the timecode was invalid. - - - - - a #GstBuffer - - - - framerate numerator - - - - framerate denominator - - - - a #GDateTime for the latest daily jam - - - - a #GstVideoTimeCodeFlags - - - - hours since the daily jam - - - - minutes since the daily jam - - - - seconds since the daily jam - - - - frames since the daily jam - - - - fields since the daily jam - - - - - - Gets the #GstVideoAFDMeta that might be present on @b. - -Note: there may be two #GstVideoAFDMeta structs for interlaced video. - - - - A #GstBuffer - - - - - - - - - - - - Gets the #GstVideoBarMeta that might be present on @b. - - - - A #GstBuffer - - - - - Gets the #GstVideoCaptionMeta that might be present on @b. - - - - A #GstBuffer - - - - - - - - - - - - - - - - - - - Find the #GstVideoMeta on @buffer with the lowest @id. - -Buffers can contain multiple #GstVideoMeta metadata items when dealing with -multiview buffers. - - - the #GstVideoMeta with lowest id (usually 0) or %NULL when there -is no such metadata on @buffer. - - - - - a #GstBuffer - - - - - - Find the #GstVideoMeta on @buffer with the given @id. - -Buffers can contain multiple #GstVideoMeta metadata items when dealing with -multiview buffers. - - - the #GstVideoMeta with @id or %NULL when there is no such metadata -on @buffer. - - - - - a #GstBuffer - - - - a metadata id - - - - - - - - - - - - - - - - - - - - - - - - - - - Find the #GstVideoRegionOfInterestMeta on @buffer with the given @id. - -Buffers can contain multiple #GstVideoRegionOfInterestMeta metadata items if -multiple regions of interests are marked on a frame. - - - the #GstVideoRegionOfInterestMeta with @id or %NULL when there is -no such metadata on @buffer. - - - - - a #GstBuffer - - - - a metadata id - - - - - - - - - - - - - Get the video alignment from the bufferpool configuration @config in -in @align - - - %TRUE if @config could be parsed correctly. - - - - - a #GstStructure - - - - a #GstVideoAlignment - - - - - - Set the video alignment in @align to the bufferpool configuration -@config - - - - - - - a #GstStructure - - - - a #GstVideoAlignment - - - - - - - - - - - - - - - Convenience function to check if the given message is a -"prepare-window-handle" message from a #GstVideoOverlay. - - - whether @msg is a "prepare-window-handle" message - - - - - a #GstMessage - - - - - - Inspect a #GstEvent and return the #GstNavigationEventType of the event, or -#GST_NAVIGATION_EVENT_INVALID if the event is not a #GstNavigation event. - - - - - - - A #GstEvent to inspect. - - - - - - Inspect a #GstNavigation command event and retrieve the enum value of the -associated command. - - - TRUE if the navigation command could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to GstNavigationCommand to receive the - type of the navigation event. - - - - - - - - - - - - A #GstEvent to inspect. - - - - A pointer to a location to receive - the string identifying the key press. The returned string is owned by the - event, and valid only until the event is unreffed. - - - - - - Retrieve the details of either a #GstNavigation mouse button press event or -a mouse button release event. Determine which type the event is using -gst_navigation_event_get_type() to retrieve the #GstNavigationEventType. - - - TRUE if the button number and both coordinates could be extracted, - otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gint that will receive the button - number associated with the event. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse button event. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse button event. - - - - - - Inspect a #GstNavigation mouse movement event and extract the coordinates -of the event. - - - TRUE if both coordinates could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse movement. - - - - - - Inspect a #GstNavigation mouse scroll event and extract the coordinates -of the event. - - - TRUE if all coordinates could be extracted, otherwise FALSE. - - - - - A #GstEvent to inspect. - - - - Pointer to a gdouble to receive the x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the y coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the delta_x coordinate of the - mouse movement. - - - - Pointer to a gdouble to receive the delta_y coordinate of the - mouse movement. - - - - - - Check a bus message to see if it is a #GstNavigation event, and return -the #GstNavigationMessageType identifying the type of the message if so. - - - The type of the #GstMessage, or -#GST_NAVIGATION_MESSAGE_INVALID if the message is not a #GstNavigation -notification. - - - - - A #GstMessage to inspect. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_ANGLES_CHANGED for notifying an application -that the current angle, or current number of angles available in a -multiangle video has changed. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - The currently selected angle. - - - - The number of viewing angles now available. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_EVENT. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - A navigation #GstEvent - - - - - - Creates a new #GstNavigation message with type -#GST_NAVIGATION_MESSAGE_MOUSE_OVER. - - - The new #GstMessage. - - - - - A #GstObject to set as source of the new message. - - - - %TRUE if the mouse has entered a clickable area of the display. -%FALSE if it over a non-clickable area. - - - - - - Parse a #GstNavigation message of type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED -and extract the @cur_angle and @n_angles parameters. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - A pointer to a #guint to receive the new - current angle number, or NULL - - - - A pointer to a #guint to receive the new angle - count, or NULL. - - - - - - Parse a #GstNavigation message of type #GST_NAVIGATION_MESSAGE_EVENT -and extract contained #GstEvent. The caller must unref the @event when done -with it. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - a pointer to a #GstEvent to receive - the contained navigation event. - - - - - - Parse a #GstNavigation message of type #GST_NAVIGATION_MESSAGE_MOUSE_OVER -and extract the active/inactive flag. If the mouse over event is marked -active, it indicates that the mouse is over a clickable area. - - - %TRUE if the message could be successfully parsed. %FALSE if not. - - - - - A #GstMessage to inspect. - - - - A pointer to a gboolean to receive the - active/inactive state, or NULL. - - - - - - Inspect a #GstQuery and return the #GstNavigationQueryType associated with -it if it is a #GstNavigation query. - - - The #GstNavigationQueryType of the query, or -#GST_NAVIGATION_QUERY_INVALID - - - - - The query to inspect - - - - - - Create a new #GstNavigation angles query. When executed, it will -query the pipeline for the set of currently available angles, which may be -greater than one in a multiangle video. - - - The new query. - - - - - Create a new #GstNavigation commands query. When executed, it will -query the pipeline for the set of currently available commands. - - - The new query. - - - - - Parse the current angle number in the #GstNavigation angles @query into the -#guint pointed to by the @cur_angle variable, and the number of available -angles into the #guint pointed to by the @n_angles variable. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - Pointer to a #guint into which to store the - currently selected angle value from the query, or NULL - - - - Pointer to a #guint into which to store the - number of angles value from the query, or NULL - - - - - - Parse the number of commands in the #GstNavigation commands @query. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - the number of commands in this query. - - - - - - Parse the #GstNavigation command query and retrieve the @nth command from -it into @cmd. If the list contains less elements than @nth, @cmd will be -set to #GST_NAVIGATION_COMMAND_INVALID. - - - %TRUE if the query could be successfully parsed. %FALSE if not. - - - - - a #GstQuery - - - - the nth command to retrieve. - - - - a pointer to store the nth command into. - - - - - - Set the #GstNavigation angles query result field in @query. - - - - - - - a #GstQuery - - - - the current viewing angle to set. - - - - the number of viewing angles to set. - - - - - - Set the #GstNavigation command query result fields in @query. The number -of commands passed must be equal to @n_commands. - - - - - - - a #GstQuery - - - - the number of commands to set. - - - - An array containing @n_cmds - @GstNavigationCommand values. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Lets you blend the @src image into the @dest image - - - - - - - The #GstVideoFrame where to blend @src in - - - - the #GstVideoFrame that we want to blend into - - - - The x offset in pixel where the @src image should be blended - - - - the y offset in pixel where the @src image should be blended - - - - the global_alpha each per-pixel alpha value is multiplied - with - - - - - - Scales a buffer containing RGBA (or AYUV) video. This is an internal -helper function which is used to scale subtitle overlays, and may be -deprecated in the near future. Use #GstVideoScaler to scale video buffers -instead. - - - - - - - the #GstVideoInfo describing the video data in @src_buffer - - - - the source buffer containing video pixels to scale - - - - the height in pixels to scale the video data in @src_buffer to - - - - the width in pixels to scale the video data in @src_buffer to - - - - pointer to a #GstVideoInfo structure that will be filled in - with the details for @dest_buffer - - - - a pointer to a #GstBuffer variable, which will be - set to a newly-allocated buffer containing the scaled pixels. - - - - - - Given the Pixel Aspect Ratio and size of an input video frame, and the -pixel aspect ratio of the intended display device, calculates the actual -display ratio the video will be rendered with. - - - A boolean indicating success and a calculated Display Ratio in the -dar_n and dar_d parameters. -The return value is FALSE in the case of integer overflow or other error. - - - - - Numerator of the calculated display_ratio - - - - Denominator of the calculated display_ratio - - - - Width of the video frame in pixels - - - - Height of the video frame in pixels - - - - Numerator of the pixel aspect ratio of the input video. - - - - Denominator of the pixel aspect ratio of the input video. - - - - Numerator of the pixel aspect ratio of the display device - - - - Denominator of the pixel aspect ratio of the display device - - - - - - - - - - - - - - - - - - Parses fixed Closed Caption #GstCaps and returns the corresponding caption -type, or %GST_VIDEO_CAPTION_TYPE_UNKNOWN. - - - #GstVideoCaptionType. - - - - - Fixed #GstCaps to parse - - - - - - Creates new caps corresponding to @type. - - - new #GstCaps - - - - - #GstVideoCaptionType - - - - - - Convert @s to a #GstVideoChromaSite - - - a #GstVideoChromaSite or %GST_VIDEO_CHROMA_SITE_UNKNOWN when @s does -not contain a valid chroma description. - - - - - a chromasite string - - - - - - Perform resampling of @width chroma pixels in @lines. - - - - - - - a #GstVideoChromaResample - - - - pixel lines - - - - the number of pixels on one line - - - - - - Create a new resampler object for the given parameters. When @h_factor or -@v_factor is > 0, upsampling will be used, otherwise subsampling is -performed. - - - a new #GstVideoChromaResample that should be freed with - gst_video_chroma_resample_free() after usage. - - - - - a #GstVideoChromaMethod - - - - a #GstVideoChromaSite - - - - #GstVideoChromaFlags - - - - the #GstVideoFormat - - - - horizontal resampling factor - - - - vertical resampling factor - - - - - - Converts @site to its string representation. - - - a string describing @site. - - - - - a #GstVideoChromaSite - - - - - - Converts the @value to the #GstVideoColorMatrix -The matrix coefficients (MatrixCoefficients) value is -defined by "ISO/IEC 23001-8 Section 7.3 Table 4" -and "ITU-T H.273 Table 4". -"H.264 Table E-5" and "H.265 Table E.5" share the identical values. - - - the matched #GstVideoColorMatrix - - - - - a ITU-T H.273 matrix coefficients value - - - - - - Get the coefficients used to convert between Y'PbPr and R'G'B' using @matrix. - -When: - -|[ - 0.0 <= [Y',R',G',B'] <= 1.0) - (-0.5 <= [Pb,Pr] <= 0.5) -]| - -the general conversion is given by: - -|[ - Y' = Kr*R' + (1-Kr-Kb)*G' + Kb*B' - Pb = (B'-Y')/(2*(1-Kb)) - Pr = (R'-Y')/(2*(1-Kr)) -]| - -and the other way around: - -|[ - R' = Y' + Cr*2*(1-Kr) - G' = Y' - Cb*2*(1-Kb)*Kb/(1-Kr-Kb) - Cr*2*(1-Kr)*Kr/(1-Kr-Kb) - B' = Y' + Cb*2*(1-Kb) -]| - - - TRUE if @matrix was a YUV color format and @Kr and @Kb contain valid - values. - - - - - a #GstVideoColorMatrix - - - - result red channel coefficient - - - - result blue channel coefficient - - - - - - Converts #GstVideoColorMatrix to the "matrix coefficients" -(MatrixCoefficients) value defined by "ISO/IEC 23001-8 Section 7.3 Table 4" -and "ITU-T H.273 Table 4". -"H.264 Table E-5" and "H.265 Table E.5" share the identical values. - - - The value of ISO/IEC 23001-8 matrix coefficients. - - - - - a #GstVideoColorMatrix - - - - - - Converts the @value to the #GstVideoColorPrimaries -The colour primaries (ColourPrimaries) value is -defined by "ISO/IEC 23001-8 Section 7.1 Table 2" and "ITU-T H.273 Table 2". -"H.264 Table E-3" and "H.265 Table E.3" share the identical values. - - - the matched #GstVideoColorPrimaries - - - - - a ITU-T H.273 colour primaries value - - - - - - Get information about the chromaticity coordinates of @primaries. - - - a #GstVideoColorPrimariesInfo for @primaries. - - - - - a #GstVideoColorPrimaries - - - - - - Converts #GstVideoColorPrimaries to the "colour primaries" (ColourPrimaries) -value defined by "ISO/IEC 23001-8 Section 7.1 Table 2" -and "ITU-T H.273 Table 2". -"H.264 Table E-3" and "H.265 Table E.3" share the identical values. - - - The value of ISO/IEC 23001-8 colour primaries. - - - - - a #GstVideoColorPrimaries - - - - - - Compute the offset and scale values for each component of @info. For each -component, (c[i] - offset[i]) / scale[i] will scale the component c[i] to the -range [0.0 .. 1.0]. - -The reverse operation (c[i] * scale[i]) + offset[i] can be used to convert -the component values in range [0.0 .. 1.0] back to their representation in -@info and @range. - - - - - - - a #GstVideoColorRange - - - - a #GstVideoFormatInfo - - - - output offsets - - - - - - output scale - - - - - - - - Convert @val to its gamma decoded value. This is the inverse operation of -@gst_video_color_transfer_encode(). - -For a non-linear value L' in the range [0..1], conversion to the linear -L is in general performed with a power function like: - -|[ - L = L' ^ gamma -]| - -Depending on @func, different formulas might be applied. Some formulas -encode a linear segment in the lower range. - - - the gamme decoded value of @val - - - - - a #GstVideoTransferFunction - - - - a value - - - - - - Convert @val to its gamma encoded value. - -For a linear value L in the range [0..1], conversion to the non-linear -(gamma encoded) L' is in general performed with a power function like: - -|[ - L' = L ^ (1 / gamma) -]| - -Depending on @func, different formulas might be applied. Some formulas -encode a linear segment in the lower range. - - - the gamme encoded value of @val - - - - - a #GstVideoTransferFunction - - - - a value - - - - - - Converts a raw video buffer into the specified output caps. - -The output caps can be any raw video formats or any image formats (jpeg, png, ...). - -The width, height and pixel-aspect-ratio can also be specified in the output caps. - - - The converted #GstSample, or %NULL if an error happened (in which case @err -will point to the #GError). - - - - - a #GstSample - - - - the #GstCaps to convert to - - - - the maximum amount of time allowed for the processing. - - - - - - Converts a raw video buffer into the specified output caps. - -The output caps can be any raw video formats or any image formats (jpeg, png, ...). - -The width, height and pixel-aspect-ratio can also be specified in the output caps. - -@callback will be called after conversion, when an error occurred or if conversion didn't -finish after @timeout. @callback will always be called from the thread default -%GMainContext, see g_main_context_get_thread_default(). If GLib before 2.22 is used, -this will always be the global default main context. - -@destroy_notify will be called after the callback was called and @user_data is not needed -anymore. - - - - - - - a #GstSample - - - - the #GstCaps to convert to - - - - the maximum amount of time allowed for the processing. - - - - %GstVideoConvertSampleCallback that will be called after conversion. - - - - extra data that will be passed to the @callback - - - - %GDestroyNotify to be called after @user_data is not needed anymore - - - - - - Create a new converter object to convert between @in_info and @out_info -with @config. - - - a #GstVideoConverter or %NULL if conversion is not possible. - - - - - a #GstVideoInfo - - - - a #GstVideoInfo - - - - a #GstStructure with configuration options - - - - - - - - - - - - - - - - - - Make a new dither object for dithering lines of @format using the -algorithm described by @method. - -Each component will be quantized to a multiple of @quantizer. Better -performance is achieved when @quantizer is a power of 2. - -@width is the width of the lines that this ditherer will handle. - - - a new #GstVideoDither - - - - - a #GstVideoDitherMethod - - - - a #GstVideoDitherFlags - - - - a #GstVideoFormat - - - - quantizer - - - - the width of the lines - - - - - - Checks if an event is a force key unit event. Returns true for both upstream -and downstream force key unit events. - - - %TRUE if the event is a valid force key unit event - - - - - A #GstEvent to check - - - - - - Creates a new downstream force key unit event. A downstream force key unit -event can be sent down the pipeline to request downstream elements to produce -a key unit. A downstream force key unit event must also be sent when handling -an upstream force key unit event to notify downstream that the latter has been -handled. - -To parse an event created by gst_video_event_new_downstream_force_key_unit() use -gst_video_event_parse_downstream_force_key_unit(). - - - The new GstEvent - - - - - the timestamp of the buffer that starts a new key unit - - - - the stream_time of the buffer that starts a new key unit - - - - the running_time of the buffer that starts a new key unit - - - - %TRUE to produce headers when starting a new key unit - - - - integer that can be used to number key units - - - - - - Creates a new Still Frame event. If @in_still is %TRUE, then the event -represents the start of a still frame sequence. If it is %FALSE, then -the event ends a still frame sequence. - -To parse an event created by gst_video_event_new_still_frame() use -gst_video_event_parse_still_frame(). - - - The new GstEvent - - - - - boolean value for the still-frame state of the event. - - - - - - Creates a new upstream force key unit event. An upstream force key unit event -can be sent to request upstream elements to produce a key unit. - -@running_time can be set to request a new key unit at a specific -running_time. If set to GST_CLOCK_TIME_NONE, upstream elements will produce a -new key unit as soon as possible. - -To parse an event created by gst_video_event_new_downstream_force_key_unit() use -gst_video_event_parse_downstream_force_key_unit(). - - - The new GstEvent - - - - - the running_time at which a new key unit should be produced - - - - %TRUE to produce headers when starting a new key unit - - - - integer that can be used to number key units - - - - - - Get timestamp, stream-time, running-time, all-headers and count in the force -key unit event. See gst_video_event_new_downstream_force_key_unit() for a -full description of the downstream force key unit event. - -@running_time will be adjusted for any pad offsets of pads it was passing through. - - - %TRUE if the event is a valid downstream force key unit event. - - - - - A #GstEvent to parse - - - - A pointer to the timestamp in the event - - - - A pointer to the stream-time in the event - - - - A pointer to the running-time in the event - - - - A pointer to the all_headers flag in the event - - - - A pointer to the count field of the event - - - - - - Parse a #GstEvent, identify if it is a Still Frame event, and -return the still-frame state from the event if it is. -If the event represents the start of a still frame, the in_still -variable will be set to TRUE, otherwise FALSE. It is OK to pass NULL for the -in_still variable order to just check whether the event is a valid still-frame -event. - -Create a still frame event using gst_video_event_new_still_frame() - - - %TRUE if the event is a valid still-frame event. %FALSE if not - - - - - A #GstEvent to parse - - - - - A boolean to receive the still-frame status from the event, or NULL - - - - - - Get running-time, all-headers and count in the force key unit event. See -gst_video_event_new_upstream_force_key_unit() for a full description of the -upstream force key unit event. - -Create an upstream force key unit event using gst_video_event_new_upstream_force_key_unit() - -@running_time will be adjusted for any pad offsets of pads it was passing through. - - - %TRUE if the event is a valid upstream force-key-unit event. %FALSE if not - - - - - A #GstEvent to parse - - - - A pointer to the running_time in the event - - - - A pointer to the all_headers flag in the event - - - - A pointer to the count field in the event - - - - - - Convert @order to a #GstVideoFieldOrder - - - the #GstVideoFieldOrder of @order or - #GST_VIDEO_FIELD_ORDER_UNKNOWN when @order is not a valid - string representation for a #GstVideoFieldOrder. - - - - - a field order - - - - - - Convert @order to its string representation. - - - @order as a string or NULL if @order in invalid. - - - - - a #GstVideoFieldOrder - - - - - - Converts a FOURCC value into the corresponding #GstVideoFormat. -If the FOURCC cannot be represented by #GstVideoFormat, -#GST_VIDEO_FORMAT_UNKNOWN is returned. - - - the #GstVideoFormat describing the FOURCC value - - - - - a FOURCC value representing raw YUV video - - - - - - Find the #GstVideoFormat for the given parameters. - - - a #GstVideoFormat or GST_VIDEO_FORMAT_UNKNOWN when the parameters to -not specify a known format. - - - - - the amount of bits used for a pixel - - - - the amount of bits used to store a pixel. This value is bigger than - @depth - - - - the endianness of the masks, #G_LITTLE_ENDIAN or #G_BIG_ENDIAN - - - - the red mask - - - - the green mask - - - - the blue mask - - - - the alpha mask, or 0 if no alpha mask - - - - - - Convert the @format string to its #GstVideoFormat. - - - the #GstVideoFormat for @format or GST_VIDEO_FORMAT_UNKNOWN when the -string is not a known format. - - - - - a format string - - - - - - Get the #GstVideoFormatInfo for @format - - - The #GstVideoFormatInfo for @format. - - - - - a #GstVideoFormat - - - - - - Get the default palette of @format. This the palette used in the pack -function for paletted formats. - - - the default palette of @format or %NULL when -@format does not have a palette. - - - - - a #GstVideoFormat - - - - size of the palette in bytes - - - - - - Converts a #GstVideoFormat value into the corresponding FOURCC. Only -a few YUV formats have corresponding FOURCC values. If @format has -no corresponding FOURCC value, 0 is returned. - - - the FOURCC corresponding to @format - - - - - a #GstVideoFormat video format - - - - - - Returns a string containing a descriptive name for -the #GstVideoFormat if there is one, or NULL otherwise. - - - the name corresponding to @format - - - - - a #GstVideoFormat video format - - - - - - Return all the raw video formats supported by GStreamer. - - - an array of #GstVideoFormat - - - - - - - the number of elements in the returned array - - - - - - - - - - - - - - - - - - Given the nominal duration of one video frame, -this function will check some standard framerates for -a close match (within 0.1%) and return one if possible, - -It will calculate an arbitrary framerate if no close -match was found, and return %FALSE. - -It returns %FALSE if a duration of 0 is passed. - - - %TRUE if a close "standard" framerate was -recognised, and %FALSE otherwise. - - - - - Nominal duration of one frame - - - - Numerator of the calculated framerate - - - - Denominator of the calculated framerate - - - - - - Convert @mode to a #GstVideoInterlaceMode - - - the #GstVideoInterlaceMode of @mode or - #GST_VIDEO_INTERLACE_MODE_PROGRESSIVE when @mode is not a valid - string representation for a #GstVideoInterlaceMode. - - - - - a mode - - - - - - Convert @mode to its string representation. - - - @mode as a string or NULL if @mode in invalid. - - - - - a #GstVideoInterlaceMode - - - - - - Return a generic raw video caps for formats defined in @formats. -If @formats is %NULL returns a caps for all the supported raw video formats, -see gst_video_formats_raw(). - - - a video @GstCaps - - - - - an array of raw #GstVideoFormat, or %NULL - - - - - - the size of @formats - - - - - - Return a generic raw video caps for formats defined in @formats with features -@features. -If @formats is %NULL returns a caps for all the supported video formats, -see gst_video_formats_raw(). - - - a video @GstCaps - - - - - an array of raw #GstVideoFormat, or %NULL - - - - - - the size of @formats - - - - the #GstCapsFeatures to set on the caps - - - - - - Extract #GstVideoMasteringDisplayInfo from @mastering - - - %TRUE if @minfo was filled with @mastering - - - - - a #GstVideoMasteringDisplayInfo - - - - a #GstStructure representing #GstVideoMasteringDisplayInfo - - - - - - - - - - - - - - - - - - Get the #GQuark for the "gst-video-scale" metadata transform operation. - - - a #GQuark - - - - - - - A const #GValue containing a list of stereo video modes - -Utility function that returns a #GValue with a GstList of packed stereo -video modes with double the height of a single view for use in -caps negotiations. Currently this is top-bottom and row-interleaved. - - - - - - - A const #GValue containing a list of stereo video modes - -Utility function that returns a #GValue with a GstList of packed -stereo video modes that have double the width/height of a single -view for use in caps negotiation. Currently this is just -'checkerboard' layout. - - - - - - - A const #GValue containing a list of stereo video modes - -Utility function that returns a #GValue with a GstList of packed stereo -video modes with double the width of a single view for use in -caps negotiations. Currently this is side-by-side, side-by-side-quincunx -and column-interleaved. - - - - - - - A const #GValue containing a list of mono video modes - -Utility function that returns a #GValue with a GstList of mono video -modes (mono/left/right) for use in caps negotiations. - - - - - - - A const #GValue containing a list of 'unpacked' stereo video modes - -Utility function that returns a #GValue with a GstList of unpacked -stereo video modes (separated/frame-by-frame/frame-by-frame-multiview) -for use in caps negotiations. - - - - - - - A boolean indicating whether the - #GST_VIDEO_MULTIVIEW_FLAGS_HALF_ASPECT flag should be set. - -Utility function that heuristically guess whether a -frame-packed stereoscopic video contains half width/height -encoded views, or full-frame views by looking at the -overall display aspect ratio. - - - - - A #GstVideoMultiviewMode - - - - Video frame width in pixels - - - - Video frame height in pixels - - - - Numerator of the video pixel-aspect-ratio - - - - Denominator of the video pixel-aspect-ratio - - - - - - - - The #GstVideoMultiviewMode value - -Given a string from a caps multiview-mode field, -output the corresponding #GstVideoMultiviewMode -or #GST_VIDEO_MULTIVIEW_MODE_NONE - - - - - multiview-mode field string from caps - - - - - - - - The caps string representation of the mode, or NULL if invalid. - -Given a #GstVideoMultiviewMode returns the multiview-mode caps string -for insertion into a caps structure - - - - - A #GstVideoMultiviewMode value - - - - - - Utility function that transforms the width/height/PAR -and multiview mode and flags of a #GstVideoInfo into -the requested mode. - - - - - - - A #GstVideoInfo structure to operate on - - - - A #GstVideoMultiviewMode value - - - - A set of #GstVideoMultiviewFlags - - - - - - - - - - - - - - - - - - This helper shall be used by classes implementing the #GstVideoOverlay -interface that want the render rectangle to be controllable using -properties. This helper will install "render-rectangle" property into the -class. - - - - - - - The class on which the properties will be installed - - - - The first free property ID to use - - - - - - This helper shall be used by classes implementing the #GstVideoOverlay -interface that want the render rectangle to be controllable using -properties. This helper will parse and set the render rectangle calling -gst_video_overlay_set_render_rectangle(). - - - %TRUE if the @property_id matches the GstVideoOverlay property - - - - - The instance on which the property is set - - - - The highest property ID. - - - - The property ID - - - - The #GValue to be set - - - - - - - - - - - - - - - - - - Make a new @method video scaler. @in_size source lines/pixels will -be scaled to @out_size destination lines/pixels. - -@n_taps specifies the amount of pixels to use from the source for one output -pixel. If n_taps is 0, this function chooses a good value automatically based -on the @method and @in_size/@out_size. - - - a #GstVideoScaler - - - - - a #GstVideoResamplerMethod - - - - #GstVideoScalerFlags - - - - number of taps to use - - - - number of source elements - - - - number of destination elements - - - - extra options - - - - - - Get the tile index of the tile at coordinates @x and @y in the tiled -image of @x_tiles by @y_tiles. - -Use this method when @mode is of type %GST_VIDEO_TILE_TYPE_INDEXED. - - - the index of the tile at @x and @y in the tiled image of - @x_tiles by @y_tiles. - - - - - a #GstVideoTileMode - - - - x coordinate - - - - y coordinate - - - - number of horizintal tiles - - - - number of vertical tiles - - - - - - - - - - - - - - - - - - Converts the @value to the #GstVideoTransferFunction -The transfer characteristics (TransferCharacteristics) value is -defined by "ISO/IEC 23001-8 Section 7.2 Table 3" -and "ITU-T H.273 Table 3". -"H.264 Table E-4" and "H.265 Table E.4" share the identical values. - - - the matched #GstVideoTransferFunction - - - - - a ITU-T H.273 transfer characteristics value - - - - - - Returns whether @from_func and @to_func are equivalent. There are cases -(e.g. BT601, BT709, and BT2020_10) where several functions are functionally -identical. In these cases, when doing conversion, we should consider them -as equivalent. Also, BT2020_12 is the same as the aforementioned three for -less than 12 bits per pixel. - - - TRUE if @from_func and @to_func can be considered equivalent. - - - - - #GstVideoTransferFunction to convert from - - - - bits per pixel to convert from - - - - #GstVideoTransferFunction to convert into - - - - bits per pixel to convert into - - - - - - Converts #GstVideoTransferFunction to the "transfer characteristics" -(TransferCharacteristics) value defined by "ISO/IEC 23001-8 Section 7.2 Table 3" -and "ITU-T H.273 Table 3". -"H.264 Table E-4" and "H.265 Table E.4" share the identical values. - - - The value of ISO/IEC 23001-8 transfer characteristics. - - - - - a #GstVideoTransferFunction - - - - - - diff --git a/gir-files/GstWebRTC-1.0.gir b/gir-files/GstWebRTC-1.0.gir deleted file mode 100644 index 4fd6b1516..000000000 --- a/gir-files/GstWebRTC-1.0.gir +++ /dev/null @@ -1,1431 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GST_WEBRTC_BUNDLE_POLICY_NONE: none -GST_WEBRTC_BUNDLE_POLICY_BALANCED: balanced -GST_WEBRTC_BUNDLE_POLICY_MAX_COMPAT: max-compat -GST_WEBRTC_BUNDLE_POLICY_MAX_BUNDLE: max-bundle -See https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1 -for more information. - - - - - - - - - - - - none - - - actpass - - - sendonly - - - recvonly - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - new - - - closed - - - failed - - - connecting - - - connected - - - - - - Close the @channel. - - - - - - - a #GstWebRTCDataChannel - - - - - - Send @data as a data message over @channel. - - - - - - - a #GstWebRTCDataChannel - - - - a #GBytes or %NULL - - - - - - Send @str as a string message over @channel. - - - - - - - a #GstWebRTCDataChannel - - - - a string or %NULL - - - - - - Close the @channel. - - - - - - - a #GstWebRTCDataChannel - - - - - - Signal that the data channel reached a low buffered amount. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - - - Signal that the data channel was closed. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - - - Signal that the data channel had an error. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - a #GError - - - - - - Signal that the data channel received a data message. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - a #GBytes or %NULL - - - - - - Signal that the data channel received a string message. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - a string or %NULL - - - - - - Signal that the data channel was opened. Should only be used by subclasses. - - - - - - - a #GstWebRTCDataChannel - - - - - - Send @data as a data message over @channel. - - - - - - - a #GstWebRTCDataChannel - - - - a #GBytes or %NULL - - - - - - Send @str as a string message over @channel. - - - - - - - a #GstWebRTCDataChannel - - - - a string or %NULL - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Close the data channel - - - - - - - - - - - - - - - - - - - - - the #GError thrown - - - - - - - - - - - a #GBytes of the data received - - - - - - - - - - - the data received as a string - - - - - - - - - - - - - - - - a #GBytes with the data - - - - - - - - - - - the data to send as a string - - - - - - - - - - - - - - - - - - - a #GstWebRTCDataChannel - - - - a #GBytes or %NULL - - - - - - - - - - - - - - a #GstWebRTCDataChannel - - - - a string or %NULL - - - - - - - - - - - - - - a #GstWebRTCDataChannel - - - - - - - - - - - - - GST_WEBRTC_DATA_CHANNEL_STATE_NEW: new -GST_WEBRTC_DATA_CHANNEL_STATE_CONNECTING: connection -GST_WEBRTC_DATA_CHANNEL_STATE_OPEN: open -GST_WEBRTC_DATA_CHANNEL_STATE_CLOSING: closing -GST_WEBRTC_DATA_CHANNEL_STATE_CLOSED: closed -See <http://w3c.github.io/webrtc-pc/#dom-rtcdatachannelstate> - - - - - - - - - - - - - - none - - - ulpfec + red - - - - - RTP component - - - RTCP component - - - - See <http://w3c.github.io/webrtc-pc/#dom-rtciceconnectionstate> - - new - - - checking - - - connected - - - completed - - - failed - - - disconnected - - - closed - - - - See <http://w3c.github.io/webrtc-pc/#dom-rtcicegatheringstate> - - new - - - gathering - - - complete - - - - - controlled - - - controlling - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - GST_WEBRTC_ICE_TRANSPORT_POLICY_ALL: all -GST_WEBRTC_ICE_TRANSPORT_POLICY_RELAY: relay -See https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24#section-4.1.1 -for more information. - - - - - - - See <http://w3c.github.io/webrtc-pc/#dom-rtcpeerconnectionstate> - - new - - - connecting - - - connected - - - disconnected - - - failed - - - closed - - - - GST_WEBRTC_PRIORITY_TYPE_VERY_LOW: very-low -GST_WEBRTC_PRIORITY_TYPE_LOW: low -GST_WEBRTC_PRIORITY_TYPE_MEDIUM: medium -GST_WEBRTC_PRIORITY_TYPE_HIGH: high -See <http://w3c.github.io/webrtc-pc/#dom-rtcprioritytype> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Direction of the transceiver. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - none - - - inactive - - - sendonly - - - recvonly - - - sendrecv - - - - GST_WEBRTC_SCTP_TRANSPORT_STATE_NEW: new -GST_WEBRTC_SCTP_TRANSPORT_STATE_CONNECTING: connecting -GST_WEBRTC_SCTP_TRANSPORT_STATE_CONNECTED: connected -GST_WEBRTC_SCTP_TRANSPORT_STATE_CLOSED: closed -See <http://w3c.github.io/webrtc-pc/#dom-rtcsctptransportstate> - - - - - - - - - - - See <http://w3c.github.io/webrtc-pc/#rtcsdptype> - - offer - - - pranswer - - - answer - - - rollback - - - - - the string representation of @type or "unknown" when @type is not - recognized. - - - - - a #GstWebRTCSDPType - - - - - - - See <https://www.w3.org/TR/webrtc/#rtcsessiondescription-class> - - - the #GstWebRTCSDPType of the description - - - - the #GstSDPMessage of the description - - - - - - a new #GstWebRTCSessionDescription from @type - and @sdp - - - - - a #GstWebRTCSDPType - - - - a #GstSDPMessage - - - - - - - - a new copy of @src - - - - - a #GstWebRTCSessionDescription - - - - - - Free @desc and all associated resources - - - - - - - a #GstWebRTCSessionDescription - - - - - - - See <http://w3c.github.io/webrtc-pc/#dom-rtcsignalingstate> - - stable - - - closed - - - have-local-offer - - - have-remote-offer - - - have-local-pranswer - - - have-remote-pranswer - - - - - codec - - - inbound-rtp - - - outbound-rtp - - - remote-inbound-rtp - - - remote-outbound-rtp - - - csrc - - - peer-connectiion - - - data-channel - - - stream - - - transport - - - candidate-pair - - - local-candidate - - - remote-candidate - - - certificate - - - - - - the string representation of @type or "unknown" when @type is not - recognized. - - - - - a #GstWebRTCSDPType - - - - - - diff --git a/gir-files/fix.sh b/gir-files/fix.sh deleted file mode 100755 index 5b5db6c2e..000000000 --- a/gir-files/fix.sh +++ /dev/null @@ -1,97 +0,0 @@ -#!/bin/bash -set -x -e - -# https://github.com/gtk-rs/gir-files/blob/master/reformat.sh -# `///` used as `//` not works in Windows in this case -for file in *.gir; do - xmlstarlet ed -P -L \ - -d '//_:doc/@line' \ - -d '//_:doc/@filename' \ - -d '///_:source-position' \ - "$file" -done - -# replace wayland structures to gpointers -xmlstarlet ed --pf --inplace \ - --update '//*[@c:type="wl_display*"]/@c:type' \ - --value gpointer \ - --update '//*[@c:type="wl_registry*"]/@c:type' \ - --value gpointer \ - --update '//*[@c:type="wl_compositor*"]/@c:type' \ - --value gpointer \ - --update '//*[@c:type="wl_subcompositor*"]/@c:type' \ - --value gpointer \ - --update '//*[@c:type="wl_shell*"]/@c:type' \ - --value gpointer \ - GstGL-1.0.gir - -# Change X11's Display* and xcb_connection_t* pointers to gpointer -xmlstarlet ed --pf --inplace \ - --insert '//_:type[@c:type="Display*"]' \ - --type attr --name 'name' --value 'gpointer' \ - --insert '//_:type[@c:type="xcb_connection_t*"]' \ - --type attr --name 'name' --value 'gpointer' \ - --update '//*[@c:type="Display*"]/@c:type' \ - --value gpointer \ - --update '//*[@c:type="xcb_connection_t*"]/@c:type' \ - --value gpointer \ - GstGL-1.0.gir - -# Remove GstMemoryEGL and EGLImage -xmlstarlet ed --pf --inplace \ - --delete '//_:record[@name="GLMemoryEGL"]' \ - --delete '//_:record[@name="GLMemoryEGLAllocator"]' \ - --delete '//_:record[@name="GLMemoryEGLAllocatorClass"]' \ - --delete '//_:record[@name="EGLImage"]' \ - --delete '//_:record[@name="GLDisplayEGLDeviceClass"]' \ - --delete '//_:class[@name="GLMemoryEGLAllocator"]' \ - --delete '//_:class[@name="GLDisplayEGLDevice"]' \ - --delete '//_:callback[@name="EGLImageDestroyNotify"]' \ - --delete '//_:constant[@name="GL_MEMORY_EGL_ALLOCATOR_NAME"]' \ - --delete '//_:function[starts-with(@name, "egl")]' \ - --delete '//_:function[starts-with(@name, "gl_memory_egl")]' \ - --delete '//_:function[@name="is_gl_memory_egl"]' \ - --delete '//_:function-macro[starts-with(@name, "egl")]' \ - --delete '//_:function-macro[starts-with(@name, "EGL")]' \ - --delete '//_:function-macro[starts-with(@name, "GL_MEMORY_EGL")]' \ - --delete '//_:function-macro[starts-with(@name, "IS_EGL_IMAGE")]' \ - --delete '//_:function-macro[starts-with(@name, "IS_GL_MEMORY_EGL")]' \ - GstGL-1.0.gir - -xmlstarlet ed --pf --inplace \ - --delete '//_:method[@c:identifier="gst_gl_display_egl_from_gl_display"]' \ - --delete '//_:method[@c:identifier="egl_from_gl_display"]' \ - GstGL-1.0.gir - -# Remove all libcheck related API -xmlstarlet ed --pf --inplace \ - --delete '//_:function[starts-with(@name, "check_")]' \ - --delete '//_:function[starts-with(@name, "buffer_straw_")]' \ - --delete '//_:callback[starts-with(@name, "Check")]' \ - --delete '//_:record[starts-with(@name, "Check")]' \ - GstCheck-1.0.gir -# Change GstVideoAncillary.data to a fixed-size 256 byte array -xmlstarlet ed --pf --inplace \ - --delete '//_:record[@name="VideoAncillary"]/_:field[@name="data"]/_:array/@length' \ - --delete '//_:record[@name="VideoAncillary"]/_:field[@name="data"]/_:array/@fixed-size' \ - --insert '//_:record[@name="VideoAncillary"]/_:field[@name="data"]/_:array' \ - --type attr --name 'fixed-size' --value '256' \ - GstVideo-1.0.gir -xmlstarlet ed --pf --inplace \ - --delete '//_:record[@name="ISO639LanguageDescriptor"]/_:field[@name="language"]/_:array/@c:type' \ - --insert '//_:record[@name="ISO639LanguageDescriptor"]/_:field[@name="language"]/_:array' \ - --type attr --name 'c:type' --value 'gchar' \ - GstMpegts-1.0.gir - -xmlstarlet ed --pf --inplace \ - --delete '//_:record[@name="MIKEYPayloadKeyData"]/_:field[@name="kv_data"]/_:array/@c:type' \ - --insert '//_:record[@name="MIKEYPayloadKeyData"]/_:field[@name="kv_data"]/_:array' \ - --type attr --name 'c:type' --value 'guint8' \ - GstSdp-1.0.gir - -# Remove duplicated enums -xmlstarlet ed --pf --inplace \ - --delete '//_:enumeration[@name="EditMode"]/_:member[starts-with(@name, "edit_")]' \ - --delete '//_:enumeration[@name="Edge"]/_:member[starts-with(@name, "edge_")]' \ - GES-1.0.gir - diff --git a/.gitignore b/sys/.gitignore similarity index 100% rename from .gitignore rename to sys/.gitignore diff --git a/.gitlab-ci.yml b/sys/.gitlab-ci.yml similarity index 100% rename from .gitlab-ci.yml rename to sys/.gitlab-ci.yml diff --git a/Cargo.toml b/sys/Cargo.toml similarity index 100% rename from Cargo.toml rename to sys/Cargo.toml diff --git a/DEVELOPMENT.md b/sys/DEVELOPMENT.md similarity index 100% rename from DEVELOPMENT.md rename to sys/DEVELOPMENT.md diff --git a/Gir_Gst.toml b/sys/Gir_Gst.toml similarity index 100% rename from Gir_Gst.toml rename to sys/Gir_Gst.toml diff --git a/Gir_GstApp.toml b/sys/Gir_GstApp.toml similarity index 100% rename from Gir_GstApp.toml rename to sys/Gir_GstApp.toml diff --git a/Gir_GstAudio.toml b/sys/Gir_GstAudio.toml similarity index 100% rename from Gir_GstAudio.toml rename to sys/Gir_GstAudio.toml diff --git a/Gir_GstBase.toml b/sys/Gir_GstBase.toml similarity index 100% rename from Gir_GstBase.toml rename to sys/Gir_GstBase.toml diff --git a/Gir_GstCheck.toml b/sys/Gir_GstCheck.toml similarity index 100% rename from Gir_GstCheck.toml rename to sys/Gir_GstCheck.toml diff --git a/Gir_GstController.toml b/sys/Gir_GstController.toml similarity index 100% rename from Gir_GstController.toml rename to sys/Gir_GstController.toml diff --git a/Gir_GstEditingServices.toml b/sys/Gir_GstEditingServices.toml similarity index 100% rename from Gir_GstEditingServices.toml rename to sys/Gir_GstEditingServices.toml diff --git a/Gir_GstGL.toml b/sys/Gir_GstGL.toml similarity index 100% rename from Gir_GstGL.toml rename to sys/Gir_GstGL.toml diff --git a/Gir_GstMpegts.toml b/sys/Gir_GstMpegts.toml similarity index 100% rename from Gir_GstMpegts.toml rename to sys/Gir_GstMpegts.toml diff --git a/Gir_GstNet.toml b/sys/Gir_GstNet.toml similarity index 100% rename from Gir_GstNet.toml rename to sys/Gir_GstNet.toml diff --git a/Gir_GstPbutils.toml b/sys/Gir_GstPbutils.toml similarity index 100% rename from Gir_GstPbutils.toml rename to sys/Gir_GstPbutils.toml diff --git a/Gir_GstPlayer.toml b/sys/Gir_GstPlayer.toml similarity index 100% rename from Gir_GstPlayer.toml rename to sys/Gir_GstPlayer.toml diff --git a/Gir_GstRtp.toml b/sys/Gir_GstRtp.toml similarity index 100% rename from Gir_GstRtp.toml rename to sys/Gir_GstRtp.toml diff --git a/Gir_GstRtsp.toml b/sys/Gir_GstRtsp.toml similarity index 100% rename from Gir_GstRtsp.toml rename to sys/Gir_GstRtsp.toml diff --git a/Gir_GstRtspServer.toml b/sys/Gir_GstRtspServer.toml similarity index 100% rename from Gir_GstRtspServer.toml rename to sys/Gir_GstRtspServer.toml diff --git a/Gir_GstSdp.toml b/sys/Gir_GstSdp.toml similarity index 100% rename from Gir_GstSdp.toml rename to sys/Gir_GstSdp.toml diff --git a/Gir_GstTag.toml b/sys/Gir_GstTag.toml similarity index 100% rename from Gir_GstTag.toml rename to sys/Gir_GstTag.toml diff --git a/Gir_GstVideo.toml b/sys/Gir_GstVideo.toml similarity index 100% rename from Gir_GstVideo.toml rename to sys/Gir_GstVideo.toml diff --git a/Gir_GstWebRTC.toml b/sys/Gir_GstWebRTC.toml similarity index 100% rename from Gir_GstWebRTC.toml rename to sys/Gir_GstWebRTC.toml diff --git a/LICENSE b/sys/LICENSE similarity index 100% rename from LICENSE rename to sys/LICENSE diff --git a/README.md b/sys/README.md similarity index 100% rename from README.md rename to sys/README.md diff --git a/ci/env.sh b/sys/ci/env.sh similarity index 100% rename from ci/env.sh rename to sys/ci/env.sh diff --git a/deny.toml b/sys/deny.toml similarity index 100% rename from deny.toml rename to sys/deny.toml diff --git a/generator.py b/sys/generator.py similarity index 100% rename from generator.py rename to sys/generator.py diff --git a/gstreamer-app-sys/CHANGELOG.md b/sys/gstreamer-app-sys/CHANGELOG.md similarity index 100% rename from gstreamer-app-sys/CHANGELOG.md rename to sys/gstreamer-app-sys/CHANGELOG.md diff --git a/gstreamer-app-sys/Cargo.toml b/sys/gstreamer-app-sys/Cargo.toml similarity index 100% rename from gstreamer-app-sys/Cargo.toml rename to sys/gstreamer-app-sys/Cargo.toml diff --git a/gstreamer-app-sys/LICENSE b/sys/gstreamer-app-sys/LICENSE similarity index 100% rename from gstreamer-app-sys/LICENSE rename to sys/gstreamer-app-sys/LICENSE diff --git a/gstreamer-app-sys/README.md b/sys/gstreamer-app-sys/README.md similarity index 100% rename from gstreamer-app-sys/README.md rename to sys/gstreamer-app-sys/README.md diff --git a/gstreamer-app-sys/build.rs b/sys/gstreamer-app-sys/build.rs similarity index 100% rename from gstreamer-app-sys/build.rs rename to sys/gstreamer-app-sys/build.rs diff --git a/gstreamer-app-sys/src/lib.rs b/sys/gstreamer-app-sys/src/lib.rs similarity index 100% rename from gstreamer-app-sys/src/lib.rs rename to sys/gstreamer-app-sys/src/lib.rs diff --git a/gstreamer-app-sys/tests/abi.rs b/sys/gstreamer-app-sys/tests/abi.rs similarity index 100% rename from gstreamer-app-sys/tests/abi.rs rename to sys/gstreamer-app-sys/tests/abi.rs diff --git a/gstreamer-app-sys/tests/constant.c b/sys/gstreamer-app-sys/tests/constant.c similarity index 100% rename from gstreamer-app-sys/tests/constant.c rename to sys/gstreamer-app-sys/tests/constant.c diff --git a/gstreamer-app-sys/tests/layout.c b/sys/gstreamer-app-sys/tests/layout.c similarity index 100% rename from gstreamer-app-sys/tests/layout.c rename to sys/gstreamer-app-sys/tests/layout.c diff --git a/gstreamer-app-sys/tests/manual.h b/sys/gstreamer-app-sys/tests/manual.h similarity index 100% rename from gstreamer-app-sys/tests/manual.h rename to sys/gstreamer-app-sys/tests/manual.h diff --git a/gstreamer-audio-sys/CHANGELOG.md b/sys/gstreamer-audio-sys/CHANGELOG.md similarity index 100% rename from gstreamer-audio-sys/CHANGELOG.md rename to sys/gstreamer-audio-sys/CHANGELOG.md diff --git a/gstreamer-audio-sys/Cargo.toml b/sys/gstreamer-audio-sys/Cargo.toml similarity index 100% rename from gstreamer-audio-sys/Cargo.toml rename to sys/gstreamer-audio-sys/Cargo.toml diff --git a/gstreamer-audio-sys/LICENSE b/sys/gstreamer-audio-sys/LICENSE similarity index 100% rename from gstreamer-audio-sys/LICENSE rename to sys/gstreamer-audio-sys/LICENSE diff --git a/gstreamer-audio-sys/README.md b/sys/gstreamer-audio-sys/README.md similarity index 100% rename from gstreamer-audio-sys/README.md rename to sys/gstreamer-audio-sys/README.md diff --git a/gstreamer-audio-sys/build.rs b/sys/gstreamer-audio-sys/build.rs similarity index 100% rename from gstreamer-audio-sys/build.rs rename to sys/gstreamer-audio-sys/build.rs diff --git a/gstreamer-audio-sys/src/lib.rs b/sys/gstreamer-audio-sys/src/lib.rs similarity index 100% rename from gstreamer-audio-sys/src/lib.rs rename to sys/gstreamer-audio-sys/src/lib.rs diff --git a/gstreamer-audio-sys/tests/abi.rs b/sys/gstreamer-audio-sys/tests/abi.rs similarity index 100% rename from gstreamer-audio-sys/tests/abi.rs rename to sys/gstreamer-audio-sys/tests/abi.rs diff --git a/gstreamer-audio-sys/tests/constant.c b/sys/gstreamer-audio-sys/tests/constant.c similarity index 100% rename from gstreamer-audio-sys/tests/constant.c rename to sys/gstreamer-audio-sys/tests/constant.c diff --git a/gstreamer-audio-sys/tests/layout.c b/sys/gstreamer-audio-sys/tests/layout.c similarity index 100% rename from gstreamer-audio-sys/tests/layout.c rename to sys/gstreamer-audio-sys/tests/layout.c diff --git a/gstreamer-audio-sys/tests/manual.h b/sys/gstreamer-audio-sys/tests/manual.h similarity index 100% rename from gstreamer-audio-sys/tests/manual.h rename to sys/gstreamer-audio-sys/tests/manual.h diff --git a/gstreamer-base-sys/CHANGELOG.md b/sys/gstreamer-base-sys/CHANGELOG.md similarity index 100% rename from gstreamer-base-sys/CHANGELOG.md rename to sys/gstreamer-base-sys/CHANGELOG.md diff --git a/gstreamer-base-sys/Cargo.toml b/sys/gstreamer-base-sys/Cargo.toml similarity index 100% rename from gstreamer-base-sys/Cargo.toml rename to sys/gstreamer-base-sys/Cargo.toml diff --git a/gstreamer-base-sys/LICENSE b/sys/gstreamer-base-sys/LICENSE similarity index 100% rename from gstreamer-base-sys/LICENSE rename to sys/gstreamer-base-sys/LICENSE diff --git a/gstreamer-base-sys/README.md b/sys/gstreamer-base-sys/README.md similarity index 100% rename from gstreamer-base-sys/README.md rename to sys/gstreamer-base-sys/README.md diff --git a/gstreamer-base-sys/build.rs b/sys/gstreamer-base-sys/build.rs similarity index 100% rename from gstreamer-base-sys/build.rs rename to sys/gstreamer-base-sys/build.rs diff --git a/gstreamer-base-sys/src/lib.rs b/sys/gstreamer-base-sys/src/lib.rs similarity index 100% rename from gstreamer-base-sys/src/lib.rs rename to sys/gstreamer-base-sys/src/lib.rs diff --git a/gstreamer-base-sys/tests/abi.rs b/sys/gstreamer-base-sys/tests/abi.rs similarity index 100% rename from gstreamer-base-sys/tests/abi.rs rename to sys/gstreamer-base-sys/tests/abi.rs diff --git a/gstreamer-base-sys/tests/constant.c b/sys/gstreamer-base-sys/tests/constant.c similarity index 100% rename from gstreamer-base-sys/tests/constant.c rename to sys/gstreamer-base-sys/tests/constant.c diff --git a/gstreamer-base-sys/tests/layout.c b/sys/gstreamer-base-sys/tests/layout.c similarity index 100% rename from gstreamer-base-sys/tests/layout.c rename to sys/gstreamer-base-sys/tests/layout.c diff --git a/gstreamer-base-sys/tests/manual.h b/sys/gstreamer-base-sys/tests/manual.h similarity index 100% rename from gstreamer-base-sys/tests/manual.h rename to sys/gstreamer-base-sys/tests/manual.h diff --git a/gstreamer-check-sys/CHANGELOG.md b/sys/gstreamer-check-sys/CHANGELOG.md similarity index 100% rename from gstreamer-check-sys/CHANGELOG.md rename to sys/gstreamer-check-sys/CHANGELOG.md diff --git a/gstreamer-check-sys/Cargo.toml b/sys/gstreamer-check-sys/Cargo.toml similarity index 100% rename from gstreamer-check-sys/Cargo.toml rename to sys/gstreamer-check-sys/Cargo.toml diff --git a/gstreamer-check-sys/LICENSE b/sys/gstreamer-check-sys/LICENSE similarity index 100% rename from gstreamer-check-sys/LICENSE rename to sys/gstreamer-check-sys/LICENSE diff --git a/gstreamer-check-sys/README.md b/sys/gstreamer-check-sys/README.md similarity index 100% rename from gstreamer-check-sys/README.md rename to sys/gstreamer-check-sys/README.md diff --git a/gstreamer-check-sys/build.rs b/sys/gstreamer-check-sys/build.rs similarity index 100% rename from gstreamer-check-sys/build.rs rename to sys/gstreamer-check-sys/build.rs diff --git a/gstreamer-check-sys/src/lib.rs b/sys/gstreamer-check-sys/src/lib.rs similarity index 100% rename from gstreamer-check-sys/src/lib.rs rename to sys/gstreamer-check-sys/src/lib.rs diff --git a/gstreamer-check-sys/tests/abi.rs b/sys/gstreamer-check-sys/tests/abi.rs similarity index 100% rename from gstreamer-check-sys/tests/abi.rs rename to sys/gstreamer-check-sys/tests/abi.rs diff --git a/gstreamer-check-sys/tests/constant.c b/sys/gstreamer-check-sys/tests/constant.c similarity index 100% rename from gstreamer-check-sys/tests/constant.c rename to sys/gstreamer-check-sys/tests/constant.c diff --git a/gstreamer-check-sys/tests/layout.c b/sys/gstreamer-check-sys/tests/layout.c similarity index 100% rename from gstreamer-check-sys/tests/layout.c rename to sys/gstreamer-check-sys/tests/layout.c diff --git a/gstreamer-check-sys/tests/manual.h b/sys/gstreamer-check-sys/tests/manual.h similarity index 100% rename from gstreamer-check-sys/tests/manual.h rename to sys/gstreamer-check-sys/tests/manual.h diff --git a/gstreamer-controller-sys/CHANGELOG.md b/sys/gstreamer-controller-sys/CHANGELOG.md similarity index 100% rename from gstreamer-controller-sys/CHANGELOG.md rename to sys/gstreamer-controller-sys/CHANGELOG.md diff --git a/gstreamer-controller-sys/Cargo.toml b/sys/gstreamer-controller-sys/Cargo.toml similarity index 100% rename from gstreamer-controller-sys/Cargo.toml rename to sys/gstreamer-controller-sys/Cargo.toml diff --git a/gstreamer-controller-sys/README.md b/sys/gstreamer-controller-sys/README.md similarity index 100% rename from gstreamer-controller-sys/README.md rename to sys/gstreamer-controller-sys/README.md diff --git a/gstreamer-controller-sys/build.rs b/sys/gstreamer-controller-sys/build.rs similarity index 100% rename from gstreamer-controller-sys/build.rs rename to sys/gstreamer-controller-sys/build.rs diff --git a/gstreamer-controller-sys/src/lib.rs b/sys/gstreamer-controller-sys/src/lib.rs similarity index 100% rename from gstreamer-controller-sys/src/lib.rs rename to sys/gstreamer-controller-sys/src/lib.rs diff --git a/gstreamer-controller-sys/tests/abi.rs b/sys/gstreamer-controller-sys/tests/abi.rs similarity index 100% rename from gstreamer-controller-sys/tests/abi.rs rename to sys/gstreamer-controller-sys/tests/abi.rs diff --git a/gstreamer-controller-sys/tests/constant.c b/sys/gstreamer-controller-sys/tests/constant.c similarity index 100% rename from gstreamer-controller-sys/tests/constant.c rename to sys/gstreamer-controller-sys/tests/constant.c diff --git a/gstreamer-controller-sys/tests/layout.c b/sys/gstreamer-controller-sys/tests/layout.c similarity index 100% rename from gstreamer-controller-sys/tests/layout.c rename to sys/gstreamer-controller-sys/tests/layout.c diff --git a/gstreamer-controller-sys/tests/manual.h b/sys/gstreamer-controller-sys/tests/manual.h similarity index 100% rename from gstreamer-controller-sys/tests/manual.h rename to sys/gstreamer-controller-sys/tests/manual.h diff --git a/gstreamer-editing-services-sys/CHANGELOG.md b/sys/gstreamer-editing-services-sys/CHANGELOG.md similarity index 100% rename from gstreamer-editing-services-sys/CHANGELOG.md rename to sys/gstreamer-editing-services-sys/CHANGELOG.md diff --git a/gstreamer-editing-services-sys/Cargo.toml b/sys/gstreamer-editing-services-sys/Cargo.toml similarity index 100% rename from gstreamer-editing-services-sys/Cargo.toml rename to sys/gstreamer-editing-services-sys/Cargo.toml diff --git a/gstreamer-editing-services-sys/README.md b/sys/gstreamer-editing-services-sys/README.md similarity index 100% rename from gstreamer-editing-services-sys/README.md rename to sys/gstreamer-editing-services-sys/README.md diff --git a/gstreamer-editing-services-sys/build.rs b/sys/gstreamer-editing-services-sys/build.rs similarity index 100% rename from gstreamer-editing-services-sys/build.rs rename to sys/gstreamer-editing-services-sys/build.rs diff --git a/gstreamer-editing-services-sys/src/lib.rs b/sys/gstreamer-editing-services-sys/src/lib.rs similarity index 100% rename from gstreamer-editing-services-sys/src/lib.rs rename to sys/gstreamer-editing-services-sys/src/lib.rs diff --git a/gstreamer-editing-services-sys/tests/abi.rs b/sys/gstreamer-editing-services-sys/tests/abi.rs similarity index 100% rename from gstreamer-editing-services-sys/tests/abi.rs rename to sys/gstreamer-editing-services-sys/tests/abi.rs diff --git a/gstreamer-editing-services-sys/tests/constant.c b/sys/gstreamer-editing-services-sys/tests/constant.c similarity index 100% rename from gstreamer-editing-services-sys/tests/constant.c rename to sys/gstreamer-editing-services-sys/tests/constant.c diff --git a/gstreamer-editing-services-sys/tests/layout.c b/sys/gstreamer-editing-services-sys/tests/layout.c similarity index 100% rename from gstreamer-editing-services-sys/tests/layout.c rename to sys/gstreamer-editing-services-sys/tests/layout.c diff --git a/gstreamer-editing-services-sys/tests/manual.h b/sys/gstreamer-editing-services-sys/tests/manual.h similarity index 100% rename from gstreamer-editing-services-sys/tests/manual.h rename to sys/gstreamer-editing-services-sys/tests/manual.h diff --git a/gstreamer-gl-sys/CHANGELOG.md b/sys/gstreamer-gl-sys/CHANGELOG.md similarity index 100% rename from gstreamer-gl-sys/CHANGELOG.md rename to sys/gstreamer-gl-sys/CHANGELOG.md diff --git a/gstreamer-gl-sys/Cargo.toml b/sys/gstreamer-gl-sys/Cargo.toml similarity index 100% rename from gstreamer-gl-sys/Cargo.toml rename to sys/gstreamer-gl-sys/Cargo.toml diff --git a/gstreamer-gl-sys/README.md b/sys/gstreamer-gl-sys/README.md similarity index 100% rename from gstreamer-gl-sys/README.md rename to sys/gstreamer-gl-sys/README.md diff --git a/gstreamer-gl-sys/build.rs b/sys/gstreamer-gl-sys/build.rs similarity index 100% rename from gstreamer-gl-sys/build.rs rename to sys/gstreamer-gl-sys/build.rs diff --git a/gstreamer-gl-sys/src/lib.rs b/sys/gstreamer-gl-sys/src/lib.rs similarity index 100% rename from gstreamer-gl-sys/src/lib.rs rename to sys/gstreamer-gl-sys/src/lib.rs diff --git a/gstreamer-gl-sys/src/manual.rs b/sys/gstreamer-gl-sys/src/manual.rs similarity index 100% rename from gstreamer-gl-sys/src/manual.rs rename to sys/gstreamer-gl-sys/src/manual.rs diff --git a/gstreamer-gl-sys/tests/abi.rs b/sys/gstreamer-gl-sys/tests/abi.rs similarity index 100% rename from gstreamer-gl-sys/tests/abi.rs rename to sys/gstreamer-gl-sys/tests/abi.rs diff --git a/gstreamer-gl-sys/tests/constant.c b/sys/gstreamer-gl-sys/tests/constant.c similarity index 100% rename from gstreamer-gl-sys/tests/constant.c rename to sys/gstreamer-gl-sys/tests/constant.c diff --git a/gstreamer-gl-sys/tests/layout.c b/sys/gstreamer-gl-sys/tests/layout.c similarity index 100% rename from gstreamer-gl-sys/tests/layout.c rename to sys/gstreamer-gl-sys/tests/layout.c diff --git a/gstreamer-gl-sys/tests/manual.h b/sys/gstreamer-gl-sys/tests/manual.h similarity index 100% rename from gstreamer-gl-sys/tests/manual.h rename to sys/gstreamer-gl-sys/tests/manual.h diff --git a/gstreamer-mpegts-sys/CHANGELOG.md b/sys/gstreamer-mpegts-sys/CHANGELOG.md similarity index 100% rename from gstreamer-mpegts-sys/CHANGELOG.md rename to sys/gstreamer-mpegts-sys/CHANGELOG.md diff --git a/gstreamer-mpegts-sys/Cargo.toml b/sys/gstreamer-mpegts-sys/Cargo.toml similarity index 100% rename from gstreamer-mpegts-sys/Cargo.toml rename to sys/gstreamer-mpegts-sys/Cargo.toml diff --git a/gstreamer-mpegts-sys/LICENSE b/sys/gstreamer-mpegts-sys/LICENSE similarity index 100% rename from gstreamer-mpegts-sys/LICENSE rename to sys/gstreamer-mpegts-sys/LICENSE diff --git a/gstreamer-mpegts-sys/README.md b/sys/gstreamer-mpegts-sys/README.md similarity index 100% rename from gstreamer-mpegts-sys/README.md rename to sys/gstreamer-mpegts-sys/README.md diff --git a/gstreamer-mpegts-sys/build.rs b/sys/gstreamer-mpegts-sys/build.rs similarity index 100% rename from gstreamer-mpegts-sys/build.rs rename to sys/gstreamer-mpegts-sys/build.rs diff --git a/gstreamer-mpegts-sys/src/lib.rs b/sys/gstreamer-mpegts-sys/src/lib.rs similarity index 100% rename from gstreamer-mpegts-sys/src/lib.rs rename to sys/gstreamer-mpegts-sys/src/lib.rs diff --git a/gstreamer-mpegts-sys/tests/abi.rs b/sys/gstreamer-mpegts-sys/tests/abi.rs similarity index 100% rename from gstreamer-mpegts-sys/tests/abi.rs rename to sys/gstreamer-mpegts-sys/tests/abi.rs diff --git a/gstreamer-mpegts-sys/tests/constant.c b/sys/gstreamer-mpegts-sys/tests/constant.c similarity index 100% rename from gstreamer-mpegts-sys/tests/constant.c rename to sys/gstreamer-mpegts-sys/tests/constant.c diff --git a/gstreamer-mpegts-sys/tests/layout.c b/sys/gstreamer-mpegts-sys/tests/layout.c similarity index 100% rename from gstreamer-mpegts-sys/tests/layout.c rename to sys/gstreamer-mpegts-sys/tests/layout.c diff --git a/gstreamer-mpegts-sys/tests/manual.h b/sys/gstreamer-mpegts-sys/tests/manual.h similarity index 100% rename from gstreamer-mpegts-sys/tests/manual.h rename to sys/gstreamer-mpegts-sys/tests/manual.h diff --git a/gstreamer-net-sys/CHANGELOG.md b/sys/gstreamer-net-sys/CHANGELOG.md similarity index 100% rename from gstreamer-net-sys/CHANGELOG.md rename to sys/gstreamer-net-sys/CHANGELOG.md diff --git a/gstreamer-net-sys/Cargo.toml b/sys/gstreamer-net-sys/Cargo.toml similarity index 100% rename from gstreamer-net-sys/Cargo.toml rename to sys/gstreamer-net-sys/Cargo.toml diff --git a/gstreamer-net-sys/LICENSE b/sys/gstreamer-net-sys/LICENSE similarity index 100% rename from gstreamer-net-sys/LICENSE rename to sys/gstreamer-net-sys/LICENSE diff --git a/gstreamer-net-sys/README.md b/sys/gstreamer-net-sys/README.md similarity index 100% rename from gstreamer-net-sys/README.md rename to sys/gstreamer-net-sys/README.md diff --git a/gstreamer-net-sys/build.rs b/sys/gstreamer-net-sys/build.rs similarity index 100% rename from gstreamer-net-sys/build.rs rename to sys/gstreamer-net-sys/build.rs diff --git a/gstreamer-net-sys/src/lib.rs b/sys/gstreamer-net-sys/src/lib.rs similarity index 100% rename from gstreamer-net-sys/src/lib.rs rename to sys/gstreamer-net-sys/src/lib.rs diff --git a/gstreamer-net-sys/tests/abi.rs b/sys/gstreamer-net-sys/tests/abi.rs similarity index 100% rename from gstreamer-net-sys/tests/abi.rs rename to sys/gstreamer-net-sys/tests/abi.rs diff --git a/gstreamer-net-sys/tests/constant.c b/sys/gstreamer-net-sys/tests/constant.c similarity index 100% rename from gstreamer-net-sys/tests/constant.c rename to sys/gstreamer-net-sys/tests/constant.c diff --git a/gstreamer-net-sys/tests/layout.c b/sys/gstreamer-net-sys/tests/layout.c similarity index 100% rename from gstreamer-net-sys/tests/layout.c rename to sys/gstreamer-net-sys/tests/layout.c diff --git a/gstreamer-net-sys/tests/manual.h b/sys/gstreamer-net-sys/tests/manual.h similarity index 100% rename from gstreamer-net-sys/tests/manual.h rename to sys/gstreamer-net-sys/tests/manual.h diff --git a/gstreamer-pbutils-sys/CHANGELOG.md b/sys/gstreamer-pbutils-sys/CHANGELOG.md similarity index 100% rename from gstreamer-pbutils-sys/CHANGELOG.md rename to sys/gstreamer-pbutils-sys/CHANGELOG.md diff --git a/gstreamer-pbutils-sys/Cargo.toml b/sys/gstreamer-pbutils-sys/Cargo.toml similarity index 100% rename from gstreamer-pbutils-sys/Cargo.toml rename to sys/gstreamer-pbutils-sys/Cargo.toml diff --git a/gstreamer-pbutils-sys/LICENSE b/sys/gstreamer-pbutils-sys/LICENSE similarity index 100% rename from gstreamer-pbutils-sys/LICENSE rename to sys/gstreamer-pbutils-sys/LICENSE diff --git a/gstreamer-pbutils-sys/README.md b/sys/gstreamer-pbutils-sys/README.md similarity index 100% rename from gstreamer-pbutils-sys/README.md rename to sys/gstreamer-pbutils-sys/README.md diff --git a/gstreamer-pbutils-sys/build.rs b/sys/gstreamer-pbutils-sys/build.rs similarity index 100% rename from gstreamer-pbutils-sys/build.rs rename to sys/gstreamer-pbutils-sys/build.rs diff --git a/gstreamer-pbutils-sys/src/lib.rs b/sys/gstreamer-pbutils-sys/src/lib.rs similarity index 100% rename from gstreamer-pbutils-sys/src/lib.rs rename to sys/gstreamer-pbutils-sys/src/lib.rs diff --git a/gstreamer-pbutils-sys/tests/abi.rs b/sys/gstreamer-pbutils-sys/tests/abi.rs similarity index 100% rename from gstreamer-pbutils-sys/tests/abi.rs rename to sys/gstreamer-pbutils-sys/tests/abi.rs diff --git a/gstreamer-pbutils-sys/tests/constant.c b/sys/gstreamer-pbutils-sys/tests/constant.c similarity index 100% rename from gstreamer-pbutils-sys/tests/constant.c rename to sys/gstreamer-pbutils-sys/tests/constant.c diff --git a/gstreamer-pbutils-sys/tests/layout.c b/sys/gstreamer-pbutils-sys/tests/layout.c similarity index 100% rename from gstreamer-pbutils-sys/tests/layout.c rename to sys/gstreamer-pbutils-sys/tests/layout.c diff --git a/gstreamer-pbutils-sys/tests/manual.h b/sys/gstreamer-pbutils-sys/tests/manual.h similarity index 100% rename from gstreamer-pbutils-sys/tests/manual.h rename to sys/gstreamer-pbutils-sys/tests/manual.h diff --git a/gstreamer-player-sys/CHANGELOG.md b/sys/gstreamer-player-sys/CHANGELOG.md similarity index 100% rename from gstreamer-player-sys/CHANGELOG.md rename to sys/gstreamer-player-sys/CHANGELOG.md diff --git a/gstreamer-player-sys/Cargo.toml b/sys/gstreamer-player-sys/Cargo.toml similarity index 100% rename from gstreamer-player-sys/Cargo.toml rename to sys/gstreamer-player-sys/Cargo.toml diff --git a/gstreamer-player-sys/LICENSE b/sys/gstreamer-player-sys/LICENSE similarity index 100% rename from gstreamer-player-sys/LICENSE rename to sys/gstreamer-player-sys/LICENSE diff --git a/gstreamer-player-sys/README.md b/sys/gstreamer-player-sys/README.md similarity index 100% rename from gstreamer-player-sys/README.md rename to sys/gstreamer-player-sys/README.md diff --git a/gstreamer-player-sys/build.rs b/sys/gstreamer-player-sys/build.rs similarity index 100% rename from gstreamer-player-sys/build.rs rename to sys/gstreamer-player-sys/build.rs diff --git a/gstreamer-player-sys/src/lib.rs b/sys/gstreamer-player-sys/src/lib.rs similarity index 100% rename from gstreamer-player-sys/src/lib.rs rename to sys/gstreamer-player-sys/src/lib.rs diff --git a/gstreamer-player-sys/tests/abi.rs b/sys/gstreamer-player-sys/tests/abi.rs similarity index 100% rename from gstreamer-player-sys/tests/abi.rs rename to sys/gstreamer-player-sys/tests/abi.rs diff --git a/gstreamer-player-sys/tests/constant.c b/sys/gstreamer-player-sys/tests/constant.c similarity index 100% rename from gstreamer-player-sys/tests/constant.c rename to sys/gstreamer-player-sys/tests/constant.c diff --git a/gstreamer-player-sys/tests/layout.c b/sys/gstreamer-player-sys/tests/layout.c similarity index 100% rename from gstreamer-player-sys/tests/layout.c rename to sys/gstreamer-player-sys/tests/layout.c diff --git a/gstreamer-player-sys/tests/manual.h b/sys/gstreamer-player-sys/tests/manual.h similarity index 100% rename from gstreamer-player-sys/tests/manual.h rename to sys/gstreamer-player-sys/tests/manual.h diff --git a/gstreamer-rtp-sys/CHANGELOG.md b/sys/gstreamer-rtp-sys/CHANGELOG.md similarity index 100% rename from gstreamer-rtp-sys/CHANGELOG.md rename to sys/gstreamer-rtp-sys/CHANGELOG.md diff --git a/gstreamer-rtp-sys/Cargo.toml b/sys/gstreamer-rtp-sys/Cargo.toml similarity index 100% rename from gstreamer-rtp-sys/Cargo.toml rename to sys/gstreamer-rtp-sys/Cargo.toml diff --git a/gstreamer-rtp-sys/README.md b/sys/gstreamer-rtp-sys/README.md similarity index 100% rename from gstreamer-rtp-sys/README.md rename to sys/gstreamer-rtp-sys/README.md diff --git a/gstreamer-rtp-sys/build.rs b/sys/gstreamer-rtp-sys/build.rs similarity index 100% rename from gstreamer-rtp-sys/build.rs rename to sys/gstreamer-rtp-sys/build.rs diff --git a/gstreamer-rtp-sys/src/lib.rs b/sys/gstreamer-rtp-sys/src/lib.rs similarity index 100% rename from gstreamer-rtp-sys/src/lib.rs rename to sys/gstreamer-rtp-sys/src/lib.rs diff --git a/gstreamer-rtp-sys/tests/abi.rs b/sys/gstreamer-rtp-sys/tests/abi.rs similarity index 100% rename from gstreamer-rtp-sys/tests/abi.rs rename to sys/gstreamer-rtp-sys/tests/abi.rs diff --git a/gstreamer-rtp-sys/tests/constant.c b/sys/gstreamer-rtp-sys/tests/constant.c similarity index 100% rename from gstreamer-rtp-sys/tests/constant.c rename to sys/gstreamer-rtp-sys/tests/constant.c diff --git a/gstreamer-rtp-sys/tests/layout.c b/sys/gstreamer-rtp-sys/tests/layout.c similarity index 100% rename from gstreamer-rtp-sys/tests/layout.c rename to sys/gstreamer-rtp-sys/tests/layout.c diff --git a/gstreamer-rtp-sys/tests/manual.h b/sys/gstreamer-rtp-sys/tests/manual.h similarity index 100% rename from gstreamer-rtp-sys/tests/manual.h rename to sys/gstreamer-rtp-sys/tests/manual.h diff --git a/gstreamer-rtsp-server-sys/CHANGELOG.md b/sys/gstreamer-rtsp-server-sys/CHANGELOG.md similarity index 100% rename from gstreamer-rtsp-server-sys/CHANGELOG.md rename to sys/gstreamer-rtsp-server-sys/CHANGELOG.md diff --git a/gstreamer-rtsp-server-sys/Cargo.toml b/sys/gstreamer-rtsp-server-sys/Cargo.toml similarity index 100% rename from gstreamer-rtsp-server-sys/Cargo.toml rename to sys/gstreamer-rtsp-server-sys/Cargo.toml diff --git a/gstreamer-rtsp-server-sys/LICENSE b/sys/gstreamer-rtsp-server-sys/LICENSE similarity index 100% rename from gstreamer-rtsp-server-sys/LICENSE rename to sys/gstreamer-rtsp-server-sys/LICENSE diff --git a/gstreamer-rtsp-server-sys/README.md b/sys/gstreamer-rtsp-server-sys/README.md similarity index 100% rename from gstreamer-rtsp-server-sys/README.md rename to sys/gstreamer-rtsp-server-sys/README.md diff --git a/gstreamer-rtsp-server-sys/build.rs b/sys/gstreamer-rtsp-server-sys/build.rs similarity index 100% rename from gstreamer-rtsp-server-sys/build.rs rename to sys/gstreamer-rtsp-server-sys/build.rs diff --git a/gstreamer-rtsp-server-sys/src/lib.rs b/sys/gstreamer-rtsp-server-sys/src/lib.rs similarity index 100% rename from gstreamer-rtsp-server-sys/src/lib.rs rename to sys/gstreamer-rtsp-server-sys/src/lib.rs diff --git a/gstreamer-rtsp-server-sys/tests/abi.rs b/sys/gstreamer-rtsp-server-sys/tests/abi.rs similarity index 100% rename from gstreamer-rtsp-server-sys/tests/abi.rs rename to sys/gstreamer-rtsp-server-sys/tests/abi.rs diff --git a/gstreamer-rtsp-server-sys/tests/constant.c b/sys/gstreamer-rtsp-server-sys/tests/constant.c similarity index 100% rename from gstreamer-rtsp-server-sys/tests/constant.c rename to sys/gstreamer-rtsp-server-sys/tests/constant.c diff --git a/gstreamer-rtsp-server-sys/tests/layout.c b/sys/gstreamer-rtsp-server-sys/tests/layout.c similarity index 100% rename from gstreamer-rtsp-server-sys/tests/layout.c rename to sys/gstreamer-rtsp-server-sys/tests/layout.c diff --git a/gstreamer-rtsp-server-sys/tests/manual.h b/sys/gstreamer-rtsp-server-sys/tests/manual.h similarity index 100% rename from gstreamer-rtsp-server-sys/tests/manual.h rename to sys/gstreamer-rtsp-server-sys/tests/manual.h diff --git a/gstreamer-rtsp-sys/CHANGELOG.md b/sys/gstreamer-rtsp-sys/CHANGELOG.md similarity index 100% rename from gstreamer-rtsp-sys/CHANGELOG.md rename to sys/gstreamer-rtsp-sys/CHANGELOG.md diff --git a/gstreamer-rtsp-sys/Cargo.toml b/sys/gstreamer-rtsp-sys/Cargo.toml similarity index 100% rename from gstreamer-rtsp-sys/Cargo.toml rename to sys/gstreamer-rtsp-sys/Cargo.toml diff --git a/gstreamer-rtsp-sys/LICENSE b/sys/gstreamer-rtsp-sys/LICENSE similarity index 100% rename from gstreamer-rtsp-sys/LICENSE rename to sys/gstreamer-rtsp-sys/LICENSE diff --git a/gstreamer-rtsp-sys/README.md b/sys/gstreamer-rtsp-sys/README.md similarity index 100% rename from gstreamer-rtsp-sys/README.md rename to sys/gstreamer-rtsp-sys/README.md diff --git a/gstreamer-rtsp-sys/build.rs b/sys/gstreamer-rtsp-sys/build.rs similarity index 100% rename from gstreamer-rtsp-sys/build.rs rename to sys/gstreamer-rtsp-sys/build.rs diff --git a/gstreamer-rtsp-sys/src/lib.rs b/sys/gstreamer-rtsp-sys/src/lib.rs similarity index 100% rename from gstreamer-rtsp-sys/src/lib.rs rename to sys/gstreamer-rtsp-sys/src/lib.rs diff --git a/gstreamer-rtsp-sys/tests/abi.rs b/sys/gstreamer-rtsp-sys/tests/abi.rs similarity index 100% rename from gstreamer-rtsp-sys/tests/abi.rs rename to sys/gstreamer-rtsp-sys/tests/abi.rs diff --git a/gstreamer-rtsp-sys/tests/constant.c b/sys/gstreamer-rtsp-sys/tests/constant.c similarity index 100% rename from gstreamer-rtsp-sys/tests/constant.c rename to sys/gstreamer-rtsp-sys/tests/constant.c diff --git a/gstreamer-rtsp-sys/tests/layout.c b/sys/gstreamer-rtsp-sys/tests/layout.c similarity index 100% rename from gstreamer-rtsp-sys/tests/layout.c rename to sys/gstreamer-rtsp-sys/tests/layout.c diff --git a/gstreamer-rtsp-sys/tests/manual.h b/sys/gstreamer-rtsp-sys/tests/manual.h similarity index 100% rename from gstreamer-rtsp-sys/tests/manual.h rename to sys/gstreamer-rtsp-sys/tests/manual.h diff --git a/gstreamer-sdp-sys/CHANGELOG.md b/sys/gstreamer-sdp-sys/CHANGELOG.md similarity index 100% rename from gstreamer-sdp-sys/CHANGELOG.md rename to sys/gstreamer-sdp-sys/CHANGELOG.md diff --git a/gstreamer-sdp-sys/Cargo.toml b/sys/gstreamer-sdp-sys/Cargo.toml similarity index 100% rename from gstreamer-sdp-sys/Cargo.toml rename to sys/gstreamer-sdp-sys/Cargo.toml diff --git a/gstreamer-sdp-sys/LICENSE b/sys/gstreamer-sdp-sys/LICENSE similarity index 100% rename from gstreamer-sdp-sys/LICENSE rename to sys/gstreamer-sdp-sys/LICENSE diff --git a/gstreamer-sdp-sys/README.md b/sys/gstreamer-sdp-sys/README.md similarity index 100% rename from gstreamer-sdp-sys/README.md rename to sys/gstreamer-sdp-sys/README.md diff --git a/gstreamer-sdp-sys/build.rs b/sys/gstreamer-sdp-sys/build.rs similarity index 100% rename from gstreamer-sdp-sys/build.rs rename to sys/gstreamer-sdp-sys/build.rs diff --git a/gstreamer-sdp-sys/src/lib.rs b/sys/gstreamer-sdp-sys/src/lib.rs similarity index 100% rename from gstreamer-sdp-sys/src/lib.rs rename to sys/gstreamer-sdp-sys/src/lib.rs diff --git a/gstreamer-sdp-sys/tests/abi.rs b/sys/gstreamer-sdp-sys/tests/abi.rs similarity index 100% rename from gstreamer-sdp-sys/tests/abi.rs rename to sys/gstreamer-sdp-sys/tests/abi.rs diff --git a/gstreamer-sdp-sys/tests/constant.c b/sys/gstreamer-sdp-sys/tests/constant.c similarity index 100% rename from gstreamer-sdp-sys/tests/constant.c rename to sys/gstreamer-sdp-sys/tests/constant.c diff --git a/gstreamer-sdp-sys/tests/layout.c b/sys/gstreamer-sdp-sys/tests/layout.c similarity index 100% rename from gstreamer-sdp-sys/tests/layout.c rename to sys/gstreamer-sdp-sys/tests/layout.c diff --git a/gstreamer-sdp-sys/tests/manual.h b/sys/gstreamer-sdp-sys/tests/manual.h similarity index 100% rename from gstreamer-sdp-sys/tests/manual.h rename to sys/gstreamer-sdp-sys/tests/manual.h diff --git a/gstreamer-sys/CHANGELOG.md b/sys/gstreamer-sys/CHANGELOG.md similarity index 100% rename from gstreamer-sys/CHANGELOG.md rename to sys/gstreamer-sys/CHANGELOG.md diff --git a/gstreamer-sys/Cargo.lock b/sys/gstreamer-sys/Cargo.lock similarity index 100% rename from gstreamer-sys/Cargo.lock rename to sys/gstreamer-sys/Cargo.lock diff --git a/gstreamer-sys/Cargo.toml b/sys/gstreamer-sys/Cargo.toml similarity index 100% rename from gstreamer-sys/Cargo.toml rename to sys/gstreamer-sys/Cargo.toml diff --git a/gstreamer-sys/LICENSE b/sys/gstreamer-sys/LICENSE similarity index 100% rename from gstreamer-sys/LICENSE rename to sys/gstreamer-sys/LICENSE diff --git a/gstreamer-sys/README.md b/sys/gstreamer-sys/README.md similarity index 100% rename from gstreamer-sys/README.md rename to sys/gstreamer-sys/README.md diff --git a/gstreamer-sys/build.rs b/sys/gstreamer-sys/build.rs similarity index 100% rename from gstreamer-sys/build.rs rename to sys/gstreamer-sys/build.rs diff --git a/gstreamer-sys/src/lib.rs b/sys/gstreamer-sys/src/lib.rs similarity index 100% rename from gstreamer-sys/src/lib.rs rename to sys/gstreamer-sys/src/lib.rs diff --git a/gstreamer-sys/tests/abi.rs b/sys/gstreamer-sys/tests/abi.rs similarity index 100% rename from gstreamer-sys/tests/abi.rs rename to sys/gstreamer-sys/tests/abi.rs diff --git a/gstreamer-sys/tests/constant.c b/sys/gstreamer-sys/tests/constant.c similarity index 100% rename from gstreamer-sys/tests/constant.c rename to sys/gstreamer-sys/tests/constant.c diff --git a/gstreamer-sys/tests/layout.c b/sys/gstreamer-sys/tests/layout.c similarity index 100% rename from gstreamer-sys/tests/layout.c rename to sys/gstreamer-sys/tests/layout.c diff --git a/gstreamer-sys/tests/manual.h b/sys/gstreamer-sys/tests/manual.h similarity index 100% rename from gstreamer-sys/tests/manual.h rename to sys/gstreamer-sys/tests/manual.h diff --git a/gstreamer-tag-sys/CHANGELOG.md b/sys/gstreamer-tag-sys/CHANGELOG.md similarity index 100% rename from gstreamer-tag-sys/CHANGELOG.md rename to sys/gstreamer-tag-sys/CHANGELOG.md diff --git a/gstreamer-tag-sys/Cargo.toml b/sys/gstreamer-tag-sys/Cargo.toml similarity index 100% rename from gstreamer-tag-sys/Cargo.toml rename to sys/gstreamer-tag-sys/Cargo.toml diff --git a/gstreamer-tag-sys/LICENSE b/sys/gstreamer-tag-sys/LICENSE similarity index 100% rename from gstreamer-tag-sys/LICENSE rename to sys/gstreamer-tag-sys/LICENSE diff --git a/gstreamer-tag-sys/README.md b/sys/gstreamer-tag-sys/README.md similarity index 100% rename from gstreamer-tag-sys/README.md rename to sys/gstreamer-tag-sys/README.md diff --git a/gstreamer-tag-sys/build.rs b/sys/gstreamer-tag-sys/build.rs similarity index 100% rename from gstreamer-tag-sys/build.rs rename to sys/gstreamer-tag-sys/build.rs diff --git a/gstreamer-tag-sys/src/lib.rs b/sys/gstreamer-tag-sys/src/lib.rs similarity index 100% rename from gstreamer-tag-sys/src/lib.rs rename to sys/gstreamer-tag-sys/src/lib.rs diff --git a/gstreamer-tag-sys/tests/abi.rs b/sys/gstreamer-tag-sys/tests/abi.rs similarity index 100% rename from gstreamer-tag-sys/tests/abi.rs rename to sys/gstreamer-tag-sys/tests/abi.rs diff --git a/gstreamer-tag-sys/tests/constant.c b/sys/gstreamer-tag-sys/tests/constant.c similarity index 100% rename from gstreamer-tag-sys/tests/constant.c rename to sys/gstreamer-tag-sys/tests/constant.c diff --git a/gstreamer-tag-sys/tests/layout.c b/sys/gstreamer-tag-sys/tests/layout.c similarity index 100% rename from gstreamer-tag-sys/tests/layout.c rename to sys/gstreamer-tag-sys/tests/layout.c diff --git a/gstreamer-tag-sys/tests/manual.h b/sys/gstreamer-tag-sys/tests/manual.h similarity index 100% rename from gstreamer-tag-sys/tests/manual.h rename to sys/gstreamer-tag-sys/tests/manual.h diff --git a/gstreamer-video-sys/CHANGELOG.md b/sys/gstreamer-video-sys/CHANGELOG.md similarity index 100% rename from gstreamer-video-sys/CHANGELOG.md rename to sys/gstreamer-video-sys/CHANGELOG.md diff --git a/gstreamer-video-sys/Cargo.toml b/sys/gstreamer-video-sys/Cargo.toml similarity index 100% rename from gstreamer-video-sys/Cargo.toml rename to sys/gstreamer-video-sys/Cargo.toml diff --git a/gstreamer-video-sys/LICENSE b/sys/gstreamer-video-sys/LICENSE similarity index 100% rename from gstreamer-video-sys/LICENSE rename to sys/gstreamer-video-sys/LICENSE diff --git a/gstreamer-video-sys/README.md b/sys/gstreamer-video-sys/README.md similarity index 100% rename from gstreamer-video-sys/README.md rename to sys/gstreamer-video-sys/README.md diff --git a/gstreamer-video-sys/build.rs b/sys/gstreamer-video-sys/build.rs similarity index 100% rename from gstreamer-video-sys/build.rs rename to sys/gstreamer-video-sys/build.rs diff --git a/gstreamer-video-sys/src/lib.rs b/sys/gstreamer-video-sys/src/lib.rs similarity index 100% rename from gstreamer-video-sys/src/lib.rs rename to sys/gstreamer-video-sys/src/lib.rs diff --git a/gstreamer-video-sys/tests/abi.rs b/sys/gstreamer-video-sys/tests/abi.rs similarity index 100% rename from gstreamer-video-sys/tests/abi.rs rename to sys/gstreamer-video-sys/tests/abi.rs diff --git a/gstreamer-video-sys/tests/constant.c b/sys/gstreamer-video-sys/tests/constant.c similarity index 100% rename from gstreamer-video-sys/tests/constant.c rename to sys/gstreamer-video-sys/tests/constant.c diff --git a/gstreamer-video-sys/tests/layout.c b/sys/gstreamer-video-sys/tests/layout.c similarity index 100% rename from gstreamer-video-sys/tests/layout.c rename to sys/gstreamer-video-sys/tests/layout.c diff --git a/gstreamer-video-sys/tests/manual.h b/sys/gstreamer-video-sys/tests/manual.h similarity index 100% rename from gstreamer-video-sys/tests/manual.h rename to sys/gstreamer-video-sys/tests/manual.h diff --git a/gstreamer-webrtc-sys/CHANGELOG.md b/sys/gstreamer-webrtc-sys/CHANGELOG.md similarity index 100% rename from gstreamer-webrtc-sys/CHANGELOG.md rename to sys/gstreamer-webrtc-sys/CHANGELOG.md diff --git a/gstreamer-webrtc-sys/Cargo.toml b/sys/gstreamer-webrtc-sys/Cargo.toml similarity index 100% rename from gstreamer-webrtc-sys/Cargo.toml rename to sys/gstreamer-webrtc-sys/Cargo.toml diff --git a/gstreamer-webrtc-sys/README.md b/sys/gstreamer-webrtc-sys/README.md similarity index 100% rename from gstreamer-webrtc-sys/README.md rename to sys/gstreamer-webrtc-sys/README.md diff --git a/gstreamer-webrtc-sys/build.rs b/sys/gstreamer-webrtc-sys/build.rs similarity index 100% rename from gstreamer-webrtc-sys/build.rs rename to sys/gstreamer-webrtc-sys/build.rs diff --git a/gstreamer-webrtc-sys/src/lib.rs b/sys/gstreamer-webrtc-sys/src/lib.rs similarity index 100% rename from gstreamer-webrtc-sys/src/lib.rs rename to sys/gstreamer-webrtc-sys/src/lib.rs diff --git a/gstreamer-webrtc-sys/tests/abi.rs b/sys/gstreamer-webrtc-sys/tests/abi.rs similarity index 100% rename from gstreamer-webrtc-sys/tests/abi.rs rename to sys/gstreamer-webrtc-sys/tests/abi.rs diff --git a/gstreamer-webrtc-sys/tests/constant.c b/sys/gstreamer-webrtc-sys/tests/constant.c similarity index 100% rename from gstreamer-webrtc-sys/tests/constant.c rename to sys/gstreamer-webrtc-sys/tests/constant.c diff --git a/gstreamer-webrtc-sys/tests/layout.c b/sys/gstreamer-webrtc-sys/tests/layout.c similarity index 100% rename from gstreamer-webrtc-sys/tests/layout.c rename to sys/gstreamer-webrtc-sys/tests/layout.c diff --git a/gstreamer-webrtc-sys/tests/manual.h b/sys/gstreamer-webrtc-sys/tests/manual.h similarity index 100% rename from gstreamer-webrtc-sys/tests/manual.h rename to sys/gstreamer-webrtc-sys/tests/manual.h